@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-clearance/src/parse/native-effects.ts

@@ -0,0 +1,49 @@
+import {
+  type NativeEffectCondition,
+  requireNativeEngine,
+} from "../native/loader.ts";
+import type { BashStage, BashStageProgram } from "./shape.ts";
+
+export const EFFECT_CLASSES = Object.freeze([
+  "read-only",
+  "write",
+  "destructive",
+  "network",
+  "shell-wrap",
+  "unknown",
+] as const);
+export type EffectClass = (typeof EFFECT_CLASSES)[number];
+
+export interface EffectClassification {
+  readonly class: EffectClass;
+  readonly reason: string;
+}
+
+export type EffectCondition = NativeEffectCondition;
+export type FileInputSpec =
+  | { readonly kind: "none" }
+  | { readonly kind: "positional"; readonly mode: "all" | "program-specific" };
+export interface EffectRegistryEntry {
+  readonly program: string;
+  readonly class: EffectClass;
+  readonly condition?: EffectCondition;
+  readonly fileInputs?: FileInputSpec;
+  readonly reason: string;
+}
+
+/** Native data table consumed by pack authoring, never reimplemented in TS. */
+export const EFFECT_REGISTRY: readonly EffectRegistryEntry[] = Object.freeze(
+  requireNativeEngine().effectRegistry() as readonly EffectRegistryEntry[],
+);
+
+export function classifyStageEffect(stage: BashStage): EffectClassification {
+  return requireNativeEngine().classifyStageEffect(stage);
+}
+
+export function getStageFileInputArgIndices(
+  stage: BashStage,
+): readonly number[] {
+  return requireNativeEngine().stageFileInputIndices(stage);
+}
+
+export type { BashStageProgram };

package/node_modules/@nklisch/pi-clearance/src/parse/native-mutation.ts

@@ -0,0 +1,20 @@
+import { requireNativeEngine } from "../native/loader.ts";
+import type {
+  MutationTrustBoundaryClassification,
+  PathFactProjectScope,
+} from "./shape.ts";
+
+export interface MutationTrustBoundaryContext {
+  readonly projectScope: PathFactProjectScope;
+  readonly homeDirectory?: string;
+}
+
+export function classifyMutationTrustBoundary(
+  absolutePath: string | undefined,
+  context: MutationTrustBoundaryContext,
+): MutationTrustBoundaryClassification {
+  return requireNativeEngine().classifyMutationTrustBoundary(
+    absolutePath,
+    context,
+  );
+}

package/node_modules/@nklisch/pi-clearance/src/parse/native-parser.ts

@@ -0,0 +1,7 @@
+import { requireNativeEngine } from "../native/loader.ts";
+import type { ToolShape } from "./shape.ts";
+
+/** Synchronous native parser exposed as a promise for existing replay seams. */
+export function analyzeBashCommand(command: string): Promise<ToolShape> {
+  return Promise.resolve(requireNativeEngine().parseBash(command));
+}

package/node_modules/@nklisch/pi-clearance/src/parse/native-path-facts.ts

@@ -0,0 +1,190 @@
+import { requireNativeEngine } from "../native/loader.ts";
+import type {
+  BashCommandShape,
+  BashIteratorEntry,
+  BashPathFact,
+  BashPathFactContext,
+  BashPathFactProvenanceEntry,
+  BashPathFacts,
+  BashStage,
+  PathFactsResolvedConfig,
+  PathScope,
+  PiBuiltinToolShape,
+  SourceSpan,
+  ToolPathFacts,
+  ToolShape,
+} from "./shape.ts";
+
+export type {
+  BashPathFactContext,
+  PathFactProjectScope,
+  PathFactsResolvedConfig,
+  ToolPathFactContext,
+} from "../contracts/index.ts";
+
+export interface BashPathFactInput {
+  readonly raw: string;
+  readonly usage: BashPathFact["usage"];
+  readonly access: BashPathFact["access"];
+  readonly program?: string;
+  readonly stageIndex?: number;
+  readonly source: SourceSpan;
+  readonly effectiveCwd?: string;
+  readonly unresolvedCwdPrefix?: boolean;
+}
+
+/** Native path-fact enrichment. The Rust engine owns all classification logic. */
+export function enrichToolShapeWithPathFacts(
+  shape: ToolShape,
+  resolvedConfig: PathFactsResolvedConfig,
+): ToolShape {
+  if (shape.kind !== "bash" && shape.kind !== "pi-tool") {
+    return shape;
+  }
+  try {
+    return requireNativeEngine().enrichPathFacts(shape, resolvedConfig);
+  } catch (error: unknown) {
+    return {
+      ...shape,
+      diagnostics: [
+        ...shape.diagnostics,
+        {
+          code: `${shape.kind}:path-facts-error`,
+          severity: "error",
+          message: `path fact derivation failed closed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        },
+      ],
+    };
+  }
+}
+
+/** Compatibility-shaped adapter used by fixture code; it still calls native. */
+export function attachBashPathFacts(
+  shape: ToolShape,
+  context: BashPathFactContext,
+): ToolShape {
+  return shape.kind === "bash"
+    ? enrichToolShapeWithPathFacts(shape, context)
+    : shape;
+}
+
+export function deriveBashPathFacts(
+  shape: BashCommandShape,
+  context: BashPathFactContext,
+): BashPathFacts {
+  const enriched = enrichToolShapeWithPathFacts(shape, context);
+  if (enriched.kind !== "bash" || enriched.pathFacts === undefined) {
+    throw new Error("native path-fact enrichment did not return bash facts");
+  }
+  return enriched.pathFacts;
+}
+
+export function derivePiBuiltinToolPathFacts(
+  shape: PiBuiltinToolShape,
+  context: BashPathFactContext,
+): ToolPathFacts {
+  const enriched = enrichToolShapeWithPathFacts(shape, context);
+  if (enriched.kind !== "pi-tool" || enriched.pathFacts === undefined) {
+    throw new Error("native path-fact enrichment did not return Pi tool facts");
+  }
+  return enriched.pathFacts;
+}
+
+/** Direct native classifier seam retained for focused path-fact assertions. */
+export function classifyBashPathFact(
+  input: BashPathFactInput,
+  context: BashPathFactContext,
+): BashPathFact {
+  return requireNativeEngine().classifyPathFact(input, context) as BashPathFact;
+}
+
+export interface IteratorReduction {
+  readonly sourceKind: "literal-word" | "literal-glob" | "mixed" | "opaque";
+  readonly entries: readonly BashPathFactProvenanceEntry[];
+  readonly scope: PathScope;
+  readonly matchedScopes: readonly PathScope[];
+  readonly concreteAbsolutePath?: string;
+  readonly staticPrefixAbsolutePath?: string;
+  readonly globApproximation: boolean;
+  readonly unknownReason?:
+    | "opaque-iterator"
+    | "iterator-mixed-unknown"
+    | "outer-scope-variable";
+}
+
+export function reduceIteratorEntry(
+  entry: BashIteratorEntry,
+  effectiveCwd: string,
+  context: BashPathFactContext,
+  home?: string,
+): BashPathFactProvenanceEntry {
+  return requireNativeEngine().reduceIteratorEntry(
+    entry,
+    effectiveCwd,
+    context,
+    home,
+  ) as BashPathFactProvenanceEntry;
+}
+
+export function reduceForLoopIterator(
+  stage: Extract<BashStage, { kind: "for-loop" }>,
+  effectiveCwd: string,
+  context: BashPathFactContext,
+  home?: string,
+): IteratorReduction {
+  return requireNativeEngine().reduceForLoopIterator(
+    stage,
+    effectiveCwd,
+    context,
+    home,
+  ) as IteratorReduction;
+}
+
+/** Platform defaults are data only; native classification uses the same table. */
+export function defaultSystemPathPrefixes(): readonly string[] {
+  if (process.platform === "win32") {
+    return [
+      "C:\\Windows",
+      "C:\\Windows\\System32",
+      "C:\\Program Files",
+      "C:\\Program Files (x86)",
+      "C:\\ProgramData",
+    ];
+  }
+  return [
+    "/etc",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/var",
+    "/dev",
+    "/proc",
+    "/sys",
+    "/boot",
+    "/lib",
+    "/lib64",
+    "/opt",
+  ];
+}
+
+/** Metadata for the native extractor registry; extraction itself is Rust-owned. */
+export interface ProgramPathExtractor {
+  readonly program: string;
+}
+
+export const PATH_ARGUMENT_EXTRACTORS: Readonly<
+  Record<string, ProgramPathExtractor>
+> = {
+  mkdir: { program: "mkdir" },
+  touch: { program: "touch" },
+  mktemp: { program: "mktemp" },
+  cargo: { program: "cargo" },
+  biome: { program: "biome" },
+  prettier: { program: "prettier" },
+  eslint: { program: "eslint" },
+  ruff: { program: "ruff" },
+};
+
+export type { BashPathFacts, ToolPathFacts };

package/node_modules/@nklisch/pi-clearance/src/parse/native-tool.ts

@@ -0,0 +1,57 @@
+import { requireNativeEngine } from "../native/loader.ts";
+import type { ToolAnalyzer } from "./registry.ts";
+import type { PiBuiltinToolShape, PiBuiltinToolSpec } from "./shape.ts";
+import {
+  SUPPORTED_PI_BUILTIN_TOOL_SPECS,
+  SUPPORTED_PI_EXTENSION_TOOL_SPECS,
+  SUPPORTED_PI_MUTATION_TOOL_SPECS,
+  SUPPORTED_PI_TOOL_SPECS,
+} from "./tool-specs.ts";
+
+export {
+  SUPPORTED_PI_BUILTIN_TOOL_SPECS,
+  SUPPORTED_PI_EXTENSION_TOOL_SPECS,
+  SUPPORTED_PI_MUTATION_TOOL_SPECS,
+  SUPPORTED_PI_TOOL_SPECS,
+};
+
+export function createPiBuiltinToolAnalyzers(): readonly ToolAnalyzer[] {
+  return SUPPORTED_PI_TOOL_SPECS.map((spec) => ({
+    toolName: spec.toolName,
+    analyze: async (input) => analyzePiBuiltinToolAsync(spec, input),
+  }));
+}
+
+export function analyzePiBuiltinTool(
+  spec: PiBuiltinToolSpec,
+  input: unknown,
+): PiBuiltinToolShape {
+  try {
+    return requireNativeEngine().analyzeTool(
+      spec.toolName,
+      input,
+    ) as PiBuiltinToolShape;
+  } catch (error: unknown) {
+    return {
+      kind: "pi-tool",
+      toolName: spec.toolName,
+      operation: spec.operation,
+      rawInput: null,
+      pathInputs: [],
+      diagnostics: [
+        {
+          code: "pi-tool:malformed-input",
+          severity: "error",
+          message: `Tool "${spec.toolName}" input could not be analyzed: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+    };
+  }
+}
+
+export async function analyzePiBuiltinToolAsync(
+  spec: PiBuiltinToolSpec,
+  input: unknown,
+): Promise<PiBuiltinToolShape> {
+  return analyzePiBuiltinTool(spec, input);
+}

package/node_modules/@nklisch/pi-clearance/src/parse/registry.ts

@@ -0,0 +1,107 @@
+import { requireNativeEngine } from "../native/loader.ts";
+import type { ShapeDiagnostic, ToolShape, UnknownToolShape } from "./shape.ts";
+
+export interface ToolAnalyzer {
+  readonly toolName: string;
+  readonly analyze: (input: unknown) => Promise<ToolShape>;
+}
+
+export interface ToolAnalyzerRegistry {
+  /** Analyze a tool input. Unknown tools and analyzer failures are always shapes. */
+  readonly analyze: (toolName: string, input: unknown) => Promise<ToolShape>;
+}
+
+export function createAnalyzerRegistry(
+  analyzers: readonly ToolAnalyzer[],
+): ToolAnalyzerRegistry {
+  const byToolName = new Map(
+    analyzers.map((analyzer) => [analyzer.toolName, analyzer]),
+  );
+
+  return {
+    analyze: async (toolName, input) => {
+      const analyzer = byToolName.get(toolName);
+      if (analyzer === undefined) {
+        return unknownToolShape(
+          toolName,
+          input,
+          unsupportedDiagnostic(toolName),
+        );
+      }
+      try {
+        return await analyzer.analyze(input);
+      } catch (error: unknown) {
+        return unknownToolShape(
+          toolName,
+          input,
+          analyzerErrorDiagnostic(error),
+        );
+      }
+    },
+  };
+}
+
+/**
+ * The runtime registry is deliberately a single native seam. There is no
+ * TypeScript parser or analyzer fallback: a missing/broken native artifact is
+ * a startup error, not an opportunity to silently arm a second implementation.
+ */
+export function createDefaultAnalyzerRegistry(): ToolAnalyzerRegistry {
+  const native = requireNativeEngine();
+  return {
+    analyze: async (toolName, input) => {
+      try {
+        return native.analyzeTool(toolName, input);
+      } catch (error: unknown) {
+        if (toolName === "edit" || toolName === "write") {
+          return {
+            kind: "pi-tool",
+            toolName,
+            operation: "mutation",
+            rawInput: null,
+            pathInputs: [],
+            diagnostics: [analyzerErrorDiagnostic(error)],
+          };
+        }
+        return unknownToolShape(
+          toolName,
+          input,
+          analyzerErrorDiagnostic(error),
+        );
+      }
+    },
+  };
+}
+
+function unknownToolShape(
+  toolName: string,
+  rawInput: unknown,
+  diagnostic: ShapeDiagnostic,
+): UnknownToolShape {
+  return {
+    kind: "unknown",
+    toolName,
+    rawInput,
+    diagnostics: [diagnostic],
+  };
+}
+
+function unsupportedDiagnostic(toolName: string): ShapeDiagnostic {
+  return {
+    code: "tool:unsupported",
+    severity: "warning",
+    message: `Tool "${toolName}" is not yet analyzed by pi-clearance`,
+  };
+}
+
+function analyzerErrorDiagnostic(error: unknown): ShapeDiagnostic {
+  return {
+    code: "tool:analyzer-error",
+    severity: "error",
+    message: `Tool analyzer failed closed: ${errorMessage(error)}`,
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "unknown analyzer error";
+}

package/node_modules/@nklisch/pi-clearance/src/parse/shape-utils.ts

@@ -0,0 +1,136 @@
+import type {
+  BashBlock,
+  BashCommandShape,
+  BashPipeline,
+  BashStage,
+  ShapeDiagnostic,
+  ToolShape,
+} from "./shape.ts";
+
+export interface ShapeSummary {
+  readonly stages: readonly string[];
+}
+
+export function flattenStages(
+  blocks: readonly BashBlock[],
+): readonly BashStage[] {
+  return blocks.flatMap((block) => block.pipeline.stages);
+}
+
+export function hasSubstitution(stage: BashStage): boolean {
+  return stage.kind === "command" && stage.substitutions.length > 0;
+}
+
+export function hasStdoutRedirect(stage: BashStage): boolean {
+  return (
+    stage.kind === "command" &&
+    stage.redirects.some(
+      (redirect) => redirect.stream === "stdout" || redirect.stream === "both",
+    )
+  );
+}
+
+export function pipelineHasTarget(
+  pipeline: BashPipeline,
+  name: string,
+): boolean {
+  return name.length > 0 && pipeline.pipeTargets.includes(name);
+}
+
+export interface CwdPrefixLiftResult {
+  readonly cwdPrefix?: string;
+  readonly blocks: readonly BashBlock[];
+  readonly diagnostics: readonly ShapeDiagnostic[];
+}
+
+export function liftCwdPrefix(
+  blocks: readonly BashBlock[],
+): CwdPrefixLiftResult {
+  const firstBlock = blocks[0];
+  if (firstBlock === undefined) return { blocks: [], diagnostics: [] };
+  const firstStage = firstBlock.pipeline.stages[0];
+  if (firstStage?.kind !== "command" || firstStage.program.program !== "cd") {
+    return { blocks: [...blocks], diagnostics: [] };
+  }
+  const lone =
+    blocks.length === 1 &&
+    firstBlock.pipeline.stages.length === 1 &&
+    firstBlock.operator === undefined &&
+    firstBlock.background !== true;
+  if (lone) return { blocks: [...blocks], diagnostics: [] };
+  const path = firstStage.program.arguments[0];
+  const canLift =
+    firstBlock.pipeline.stages.length === 1 &&
+    firstStage.program.resolvable &&
+    firstStage.program.arguments.length === 1 &&
+    firstStage.program.flags.length === 0 &&
+    firstStage.program.environment.length === 0 &&
+    !hasSubstitution(firstStage) &&
+    firstStage.redirects.length === 0 &&
+    firstBlock.operator === "and" &&
+    firstBlock.background !== true;
+  if (canLift && path !== undefined) {
+    return { cwdPrefix: path, blocks: blocks.slice(1), diagnostics: [] };
+  }
+  return {
+    blocks: [...blocks],
+    diagnostics: [cwdPrefixUnsupportedDiagnostic(firstStage)],
+  };
+}
+
+export function summarizeShape(shape: ToolShape): ShapeSummary {
+  return shape.kind === "bash"
+    ? { stages: stageProgramNames(shape) }
+    : { stages: [] };
+}
+
+export function primaryExecutableFromShape(
+  shape: ToolShape | undefined,
+): string | undefined {
+  if (shape?.kind !== "bash") return undefined;
+  const fromBlocks = flattenStages(shape.blocks).find(
+    (stage) =>
+      stage.kind === "command" &&
+      stage.program.resolvable &&
+      stage.program.program.length > 0,
+  );
+  if (fromBlocks?.kind === "command") return fromBlocks.program.program;
+  return summarizeShape(shape).stages.find((stage) => stage.length > 0);
+}
+
+export type EmbeddedShellPiToolShape = Extract<
+  ToolShape,
+  { kind: "pi-tool" }
+> & {
+  readonly embeddedShell?: {
+    readonly command?: BashCommandShape;
+  };
+};
+
+export function asEmbeddedShellShape(
+  shape: ToolShape,
+): EmbeddedShellPiToolShape | undefined {
+  return shape.kind === "pi-tool" && shape.operation === "embedded-shell"
+    ? (shape as EmbeddedShellPiToolShape)
+    : undefined;
+}
+
+function stageProgramNames(shape: BashCommandShape): readonly string[] {
+  return shape.stages.map((stage) =>
+    stage.kind === "command" && stage.program.resolvable
+      ? stage.program.program
+      : "",
+  );
+}
+
+export function cwdPrefixUnsupportedDiagnostic(
+  stage: BashStage,
+): ShapeDiagnostic {
+  return {
+    code: "bash:cwd-prefix-unsupported",
+    message:
+      "Leading cd command is not a supported cwd-prefix form and requires review",
+    severity: "warning",
+    ...(stage.kind === "command" ? { source: stage.span } : {}),
+  };
+}