@osovv/grace-cli 3.3.0 → 3.4.0

package/README.md

@@ -10,13 +10,13 @@ This repository packages GRACE as reusable skills for coding agents. The current
 - knowledge-graph synchronization
 - controller-managed sequential or multi-agent implementation
 
-Current packaged version: `3.3.0`
+Current packaged version: `3.4.0`
 
 ## What Changed In This Version
 
-- Removed profile selection from `grace lint`; the CLI now validates only against the current GRACE artifact set.
-- Limited `.grace-lint.json` to the current config schema, such as `ignoredDirs`.
-- Kept the role-aware/adaptive lint model while making older GRACE repos fail loudly until they are updated.
+- Added a rich Python adapter without `pyright` for `grace lint`.
+- Kept TypeScript/JavaScript on the TypeScript compiler API for exact export analysis.
+- Made adapter failures non-fatal so linting can continue with structural checks and warnings.
 
 ## Repository Layout
 
@@ -195,6 +195,17 @@ The lint command is role-aware and adapter-aware:
 - export-map parity uses language adapters where available
 - file behavior is driven by semantic roles instead of filename masks
 
+Current rich adapters:
+
+- TypeScript/JavaScript via the TypeScript compiler API
+- Python via the Python standard-library AST, without `pyright`
+
+Current adapter behavior:
+
+- TypeScript/JavaScript export analysis is treated as exact
+- Python export analysis is exact when `__all__` is explicit, otherwise heuristic
+- other languages still benefit from structural GRACE checks even when rich export analysis is not available yet
+
 Optional `MODULE_CONTRACT` fields for linting:
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/grace-cli",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "GRACE CLI for linting semantic markup, contracts, and GRACE XML artifacts with a Bun-powered grace binary.",
   "license": "MIT",
   "homepage": "https://github.com/osovv/grace-marketplace#readme",
@@ -16,6 +16,8 @@
     "cli",
     "lint",
     "bun",
+    "python",
+    "typescript",
     "semantic-markup",
     "knowledge-graph"
   ],

package/src/grace.ts

@@ -7,7 +7,7 @@ import { lintCommand } from "./grace-lint";
 const main = defineCommand({
   meta: {
     name: "grace",
-    version: "3.3.0",
+    version: "3.4.0",
     description: "GRACE CLI for linting semantic markup and GRACE project artifacts.",
   },
   subCommands: {

package/src/lint/adapters/base.ts

@@ -1,9 +1,10 @@
 import path from "node:path";
 
 import type { LanguageAdapter } from "../types";
+import { createPythonAdapter } from "./python";
 import { createTypeScriptAdapter } from "./typescript";
 
-const adapters: LanguageAdapter[] = [createTypeScriptAdapter()];
+const adapters: LanguageAdapter[] = [createTypeScriptAdapter(), createPythonAdapter()];
 
 export function getLanguageAdapter(filePath: string) {
   const normalizedPath = path.normalize(filePath);

package/src/lint/adapters/python.ts

@@ -0,0 +1,264 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+import type { LanguageAdapter, LanguageAnalysis } from "../types";
+
+const PY_EXTENSIONS = new Set([".py", ".pyi"]);
+const PYTHON_BINARIES = ["python3", "python"];
+
+const PYTHON_ANALYZER_SCRIPT = String.raw`
+import ast
+import json
+import os
+import sys
+
+source = sys.stdin.read()
+file_path = sys.argv[1]
+base_name = os.path.basename(file_path)
+
+
+def is_public(name):
+    return isinstance(name, str) and len(name) > 0 and not name.startswith("_")
+
+
+def extract_target_names(target):
+    if isinstance(target, ast.Name):
+        return [target.id]
+    if isinstance(target, (ast.Tuple, ast.List)):
+        names = []
+        for item in target.elts:
+            names.extend(extract_target_names(item))
+        return names
+    return []
+
+
+def extract_string_sequence(node):
+    if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
+        values = []
+        for element in node.elts:
+            if not isinstance(element, ast.Constant) or not isinstance(element.value, str):
+                return None
+            values.append(element.value)
+        return values
+    return None
+
+
+def is_main_guard(test):
+    if not isinstance(test, ast.Compare):
+        return False
+    if len(test.ops) != 1 or len(test.comparators) != 1:
+        return False
+    left = test.left
+    comparator = test.comparators[0]
+    return (
+        isinstance(left, ast.Name)
+        and left.id == "__name__"
+        and isinstance(test.ops[0], ast.Eq)
+        and isinstance(comparator, ast.Constant)
+        and comparator.value == "__main__"
+    )
+
+
+def imported_name(alias):
+    return alias.asname or alias.name.split(".", 1)[0]
+
+
+local_public = set()
+imported_public = set()
+explicit_all = None
+has_wildcard_reexport = False
+direct_reexport_count = 0
+local_implementation_count = 0
+uses_test_framework = False
+has_main_entrypoint = False
+
+try:
+    tree = ast.parse(source, filename=file_path)
+except SyntaxError as exc:
+    message = f"{exc.msg} at line {exc.lineno}:{exc.offset}" if exc.lineno else exc.msg
+    sys.stderr.write(message)
+    sys.exit(2)
+
+for node in tree.body:
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            imported = imported_name(alias)
+            if is_public(imported):
+                imported_public.add(imported)
+            if alias.name == "pytest" or alias.name.startswith("unittest"):
+                uses_test_framework = True
+        continue
+
+    if isinstance(node, ast.ImportFrom):
+        module = node.module or ""
+        if module == "pytest" or module.startswith("unittest"):
+            uses_test_framework = True
+        if any(alias.name == "*" for alias in node.names):
+            has_wildcard_reexport = True
+            direct_reexport_count += 1
+            continue
+        public_imports = 0
+        for alias in node.names:
+            imported = imported_name(alias)
+            if is_public(imported):
+                imported_public.add(imported)
+                public_imports += 1
+        if public_imports:
+            direct_reexport_count += 1
+        continue
+
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        local_implementation_count += 1
+        if node.name.startswith("test_"):
+            uses_test_framework = True
+        if is_public(node.name):
+            local_public.add(node.name)
+        continue
+
+    if isinstance(node, ast.ClassDef):
+        local_implementation_count += 1
+        if node.name.startswith("Test"):
+            uses_test_framework = True
+        if is_public(node.name):
+            local_public.add(node.name)
+        continue
+
+    if isinstance(node, ast.Assign):
+        for target in node.targets:
+            for name in extract_target_names(target):
+                if name == "__all__":
+                    sequence = extract_string_sequence(node.value)
+                    if sequence is not None:
+                        explicit_all = sequence
+                    continue
+                if is_public(name):
+                    local_public.add(name)
+                    local_implementation_count += 1
+        continue
+
+    if isinstance(node, ast.AnnAssign):
+        for name in extract_target_names(node.target):
+            if name == "__all__":
+                sequence = extract_string_sequence(node.value)
+                if sequence is not None:
+                    explicit_all = sequence
+                continue
+            if is_public(name):
+                local_public.add(name)
+                local_implementation_count += 1
+        continue
+
+    if isinstance(node, ast.If) and is_main_guard(node.test):
+        has_main_entrypoint = True
+
+if explicit_all is not None:
+    export_names = sorted({name for name in explicit_all if isinstance(name, str)})
+    export_confidence = "exact"
+else:
+    export_names = set(local_public)
+    if base_name == "__init__.py":
+        export_names.update(imported_public)
+    export_names = sorted(export_names)
+    export_confidence = "heuristic"
+
+local_export_count = sum(1 for name in export_names if name in local_public)
+
+print(json.dumps({
+    "exports": export_names,
+    "valueExports": export_names,
+    "typeExports": [],
+    "exportConfidence": export_confidence,
+    "hasDefaultExport": False,
+    "hasWildcardReExport": has_wildcard_reexport,
+    "hasMainEntrypoint": has_main_entrypoint,
+    "directReExportCount": direct_reexport_count,
+    "localExportCount": local_export_count,
+    "localImplementationCount": local_implementation_count,
+    "usesTestFramework": uses_test_framework,
+}))
+`;
+
+function createEmptyAnalysis(): LanguageAnalysis {
+  return {
+    adapterId: "python",
+    exports: new Set<string>(),
+    valueExports: new Set<string>(),
+    typeExports: new Set<string>(),
+    exportConfidence: "heuristic",
+    hasDefaultExport: false,
+    hasWildcardReExport: false,
+    hasMainEntrypoint: false,
+    directReExportCount: 0,
+    localExportCount: 0,
+    localImplementationCount: 0,
+    usesTestFramework: false,
+  };
+}
+
+function normalizeResult(output: string) {
+  const parsed = JSON.parse(output) as {
+    exports: string[];
+    valueExports: string[];
+    typeExports: string[];
+    exportConfidence: "exact" | "heuristic";
+    hasDefaultExport: boolean;
+    hasWildcardReExport: boolean;
+    hasMainEntrypoint: boolean;
+    directReExportCount: number;
+    localExportCount: number;
+    localImplementationCount: number;
+    usesTestFramework: boolean;
+  };
+
+  const analysis = createEmptyAnalysis();
+  analysis.exports = new Set(parsed.exports ?? []);
+  analysis.valueExports = new Set(parsed.valueExports ?? []);
+  analysis.typeExports = new Set(parsed.typeExports ?? []);
+  analysis.exportConfidence = parsed.exportConfidence ?? "heuristic";
+  analysis.hasDefaultExport = Boolean(parsed.hasDefaultExport);
+  analysis.hasWildcardReExport = Boolean(parsed.hasWildcardReExport);
+  analysis.hasMainEntrypoint = Boolean(parsed.hasMainEntrypoint);
+  analysis.directReExportCount = Number(parsed.directReExportCount ?? 0);
+  analysis.localExportCount = Number(parsed.localExportCount ?? 0);
+  analysis.localImplementationCount = Number(parsed.localImplementationCount ?? 0);
+  analysis.usesTestFramework = Boolean(parsed.usesTestFramework);
+  return analysis;
+}
+
+function runPythonAnalyzer(filePath: string, text: string) {
+  for (const binary of PYTHON_BINARIES) {
+    const run = spawnSync(binary, ["-c", PYTHON_ANALYZER_SCRIPT, filePath], {
+      input: text,
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024,
+    });
+
+    if (run.error) {
+      const code = (run.error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") {
+        continue;
+      }
+      throw run.error;
+    }
+
+    if (run.status === 0) {
+      return normalizeResult(run.stdout);
+    }
+
+    throw new Error(run.stderr.trim() || run.stdout.trim() || `Python analyzer failed via ${binary}.`);
+  }
+
+  throw new Error("Python adapter requires `python3` or `python` on PATH when linting Python files.");
+}
+
+export function createPythonAdapter(): LanguageAdapter {
+  return {
+    id: "python",
+    supports(filePath) {
+      return PY_EXTENSIONS.has(path.extname(filePath));
+    },
+    analyze(filePath, text) {
+      return runPythonAnalyzer(filePath, text);
+    },
+  };
+}

package/src/lint/adapters/typescript.ts

@@ -73,8 +73,10 @@ export function createTypeScriptAdapter(): LanguageAdapter {
         exports: new Set<string>(),
         valueExports: new Set<string>(),
         typeExports: new Set<string>(),
+        exportConfidence: "exact",
         hasDefaultExport: false,
         hasWildcardReExport: false,
+        hasMainEntrypoint: false,
         directReExportCount: 0,
         localExportCount: 0,
         localImplementationCount: 0,

package/src/lint/core.ts

@@ -41,6 +41,7 @@ const CODE_EXTENSIONS = new Set([
   ".mts",
   ".cts",
   ".py",
+  ".pyi",
   ".go",
   ".java",
   ".kt",
@@ -432,6 +433,10 @@ function inferRole(contract: ModuleContractInfo | null, analysis: LanguageAnalys
     return "CONFIG";
   }
 
+  if (analysis?.hasMainEntrypoint) {
+    return "SCRIPT";
+  }
+
   if (analysis && mentionsScript && analysis.exports.size === 0) {
     return "SCRIPT";
   }
@@ -564,6 +569,17 @@ function lintExportMapParity(
     return;
   }
 
+  const exportSeverity = analysis.exportConfidence === "exact" ? "error" : "warning";
+
+  if (analysis.exportConfidence === "heuristic") {
+    addIssue(result, {
+      severity: "warning",
+      code: "analysis.heuristic-export-surface",
+      file: relativePath,
+      message: `The ${analysis.adapterId} adapter inferred exports heuristically for this file. Exact MODULE_MAP parity may require explicit file ROLE/MAP_MODE or stronger language-specific export declarations.`,
+    });
+  }
+
   if (analysis.hasWildcardReExport) {
     addIssue(result, {
       severity: "warning",
@@ -577,7 +593,7 @@ function lintExportMapParity(
   const mappedSymbols = new Set(items.flatMap((item) => (item.symbolName ? [item.symbolName] : [])));
   if (mappedSymbols.size === 0 && analysis.exports.size > 0) {
     addIssue(result, {
-      severity: "error",
+      severity: exportSeverity,
       code: "markup.module-map-missing-symbol-entries",
       file: relativePath,
       message: "MODULE_MAP should list concrete symbol names when MAP_MODE resolves to EXPORTS.",
@@ -588,7 +604,7 @@ function lintExportMapParity(
   for (const exportName of analysis.exports) {
     if (!mappedSymbols.has(exportName)) {
       addIssue(result, {
-        severity: "error",
+        severity: exportSeverity,
         code: "markup.module-map-missing-export",
         file: relativePath,
         message: `MODULE_MAP is missing the exported symbol \`${exportName}\`.`,
@@ -657,7 +673,19 @@ function lintGovernedFile(result: LintResult, root: string, filePath: string, te
   const contract = moduleContractSection ? parseModuleContract(moduleContractSection) : null;
   const mapItems = moduleMapSection ? parseModuleMapItems(moduleMapSection) : [];
   const adapter = getLanguageAdapter(filePath);
-  const analysis = adapter ? adapter.analyze(filePath, text) : null;
+  let analysis: LanguageAnalysis | null = null;
+  if (adapter) {
+    try {
+      analysis = adapter.analyze(filePath, text);
+    } catch (error) {
+      addIssue(result, {
+        severity: "warning",
+        code: "analysis.adapter-failed",
+        file: relativePath,
+        message: `${adapter.id} adapter failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  }
   const role = inferRole(contract, analysis);
   const mapMode = inferMapMode(contract, role, mapItems, analysis);
 

package/src/lint/types.ts

@@ -54,8 +54,10 @@ export type LanguageAnalysis = {
   exports: Set<string>;
   valueExports: Set<string>;
   typeExports: Set<string>;
+  exportConfidence: "exact" | "heuristic";
   hasDefaultExport: boolean;
   hasWildcardReExport: boolean;
+  hasMainEntrypoint: boolean;
   directReExportCount: number;
   localExportCount: number;
   localImplementationCount: number;