fallow-type-aware 0.0.0-bootstrap.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bart Waardenburg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# fallow-type-aware
+
+Optional TypeScript-Go semantic refinement sidecar for Fallow. It accepts one
+versioned JSON request on stdin and writes one JSON response to stdout.
+
+The sidecar is deliberately narrower than a general type-aware linter. Protocol
+v6 accepts a bounded set of tagged `symbol-use`, `symbol-trace`, `api-surface`,
+`symbol-impact`, and `type-coupling` queries. Each selected TypeScript project
+creates one Program. Symbol use, trace, and impact queries share one indexed
+source traversal per Program.
+
+Symbol identities include the canonical project-relative path, value or type
+namespace, declaration kind, exported and local name, one-based line,
+zero-based UTF-8 byte column, and optional owner. Results keep their semantic
+assertion separate from `complete`, `partial`, or `unavailable` status. Evidence
+and every operation-specific array are deterministic and bounded, with totals,
+omissions, reason codes, actions, and truncation reported explicitly.
+
+Unsafe project state never manufactures certainty. Structural diagnostics,
+unknown identities, missing projects, unsupported syntax, dynamic behavior,
+and capacity limits retain syntactic findings or produce an explicit advisory
+gap. Required interfaces, abstract members, and overrides are returned as exact
+contract evidence. Complete negative evidence carries an exact UTF-8 byte span
+and SHA-256 declaration guard, but Fallow owns the final decision and fix
+policy. The sidecar does not emit TypeScript compiler diagnostics as Fallow
+findings and does not implement generic typed lint rules.
+
+## Run locally
+
+```sh
+npm ci
+npm test
+./fallow-type-aware.mjs < request.json
+```
+
+The implementation pins `typescript@7.0.2` because `typescript/unstable/sync`
+is an explicitly unstable API. That backend detail is contained behind
+Fallow's stable, exact-version protocol. Package version, protocol version, and
+TypeScript backend version are validated independently. See
+[`docs/type-aware-analysis.md`](../../docs/type-aware-analysis.md)
+for the Fallow integration contract, safety policy, and current limitations.
+
+## Release
+
+Publication remains a separate release action. The package is designed to be
+installed as an exact-version optional companion and launched through a
+verified absolute path supplied by Fallow. It does not search the analyzed
+project or arbitrary PATH entries for a backend.

package/fallow-type-aware.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { run } from "./src/cli.mjs";
+
+try {
+  await run({ input: process.stdin, output: process.stdout, args: process.argv.slice(2) });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`fallow-type-aware: ${message}\n`);
+  process.exitCode = 2;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "fallow-type-aware",
+  "version": "0.0.0-bootstrap.0",
+  "description": "Optional TypeScript-Go semantic refinement sidecar for Fallow",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fallow-rs/fallow.git",
+    "directory": "tools/type-aware-sidecar"
+  },
+  "files": [
+    "fallow-type-aware.mjs",
+    "src"
+  ],
+  "type": "module",
+  "bin": {
+    "fallow-type-aware": "fallow-type-aware.mjs"
+  },
+  "scripts": {
+    "bench": "node bench/session.mjs",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@codspeed/tinybench-plugin": "5.7.1",
+    "tinybench": "6.1.2"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,167 @@
+import path from "node:path";
+import { createInterface } from "node:readline";
+
+import {
+  ANALYSIS_OPERATION,
+  SESSION_ENVELOPE_TYPES,
+  STATUS_OPERATION,
+  WIRE_PROTOCOL_VERSION,
+} from "./generated-protocol.mjs";
+import { analyzeSemanticQueries, createSemanticSession } from "./semantic.mjs";
+import { createSemanticResponse, createStatusResponse, parseRequest } from "./protocol.mjs";
+
+const MAX_REQUEST_BYTES = 8 * 1024 * 1024;
+const [ANALYZE_ENVELOPE, SHUTDOWN_ENVELOPE] = SESSION_ENVELOPE_TYPES;
+const STATUS_FIELDS = [
+  ["protocol_version", WIRE_PROTOCOL_VERSION],
+  ["operation", STATUS_OPERATION],
+];
+
+export const readAll = async (input, maximumBytes = MAX_REQUEST_BYTES) => {
+  const chunks = [];
+  let byteLength = 0;
+  for await (const chunk of input) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    byteLength += buffer.byteLength;
+    if (byteLength > maximumBytes) {
+      throw new Error(`stdin exceeded the ${maximumBytes} byte request limit`);
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+};
+
+const writeJson = (output, value) => {
+  output.write(`${JSON.stringify(value)}\n`);
+};
+
+const handleArguments = (args, output) => {
+  if (args.length === 1 && args[0] === "--status") {
+    writeJson(output, createStatusResponse());
+    return true;
+  }
+  if (args.length === 1 && args[0] === "--session") {
+    return false;
+  }
+  if (args.length > 0) {
+    throw new Error(`unknown argument: ${args[0]}`);
+  }
+  return false;
+};
+
+const sessionFileChanges = (value, root) => {
+  if (value === undefined) return undefined;
+  if (value?.invalidate_all === true && Object.keys(value).length === 1) {
+    return { invalidateAll: true };
+  }
+  const allowed = new Set(["changed", "created", "deleted"]);
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    Object.keys(value).some((key) => !allowed.has(key))
+  ) {
+    throw new Error("session file_changes contains an unsupported field");
+  }
+  const resolveFiles = (files, field) => {
+    if (files === undefined) return undefined;
+    if (!Array.isArray(files)) throw new Error(`session file_changes.${field} must be an array`);
+    return files.map((file) => {
+      if (typeof file !== "string" || file.length === 0 || path.isAbsolute(file)) {
+        throw new Error(`session file_changes.${field} must contain project-relative paths`);
+      }
+      const resolved = path.resolve(root, file);
+      const relative = path.relative(root, resolved);
+      if (relative === ".." || relative.startsWith(`..${path.sep}`)) {
+        throw new Error(`session file_changes.${field} must stay within the session root`);
+      }
+      return resolved;
+    });
+  };
+  return {
+    ...(value.changed ? { changed: resolveFiles(value.changed, "changed") } : {}),
+    ...(value.created ? { created: resolveFiles(value.created, "created") } : {}),
+    ...(value.deleted ? { deleted: resolveFiles(value.deleted, "deleted") } : {}),
+  };
+};
+
+const runSession = async (input, output) => {
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  let session;
+  let root;
+  try {
+    for await (const line of lines) {
+      if (Buffer.byteLength(line, "utf8") > MAX_REQUEST_BYTES) {
+        throw new Error(`session request exceeded the ${MAX_REQUEST_BYTES} byte limit`);
+      }
+      const envelope = parseJsonRequest(line);
+      if (envelope?.type === SHUTDOWN_ENVELOPE) return;
+      if (
+        envelope?.type !== ANALYZE_ENVELOPE ||
+        !Number.isSafeInteger(envelope.request_id) ||
+        envelope.request_id < 0 ||
+        !Number.isSafeInteger(envelope.revision) ||
+        envelope.revision < 1
+      ) {
+        throw new Error("invalid semantic session envelope");
+      }
+      const request = parseRequest(envelope.request);
+      if (!session) {
+        root = request.root;
+        session = createSemanticSession(root);
+      }
+      if (request.root !== root) throw new Error("semantic session root mismatch");
+      const startedAt = performance.now();
+      const result = session.analyze(request, {
+        revision: envelope.revision,
+        fileChanges: sessionFileChanges(envelope.file_changes, root),
+      });
+      writeJson(output, {
+        request_id: envelope.request_id,
+        revision: envelope.revision,
+        response: responseFor(request, result, performance.now() - startedAt),
+      });
+    }
+  } finally {
+    session?.close();
+  }
+};
+
+const parseJsonRequest = (source) => {
+  try {
+    return JSON.parse(source);
+  } catch {
+    throw new Error("stdin must contain one valid JSON request");
+  }
+};
+
+const isStatusRequest = (request) =>
+  Object.keys(request ?? {}).length === STATUS_FIELDS.length &&
+  STATUS_FIELDS.every(([name, value]) => request[name] === value);
+
+const responseFor = (request, result, elapsedMs) => {
+  if (request.protocolVersion !== WIRE_PROTOCOL_VERSION) {
+    throw new Error(`unsupported protocol_version ${String(request.protocolVersion)}`);
+  }
+  return createSemanticResponse({ ...result, elapsedMs });
+};
+
+export const run = async ({ input, output, args = [] }) => {
+  if (args.length === 1 && args[0] === "--session") {
+    await runSession(input, output);
+    return;
+  }
+  if (handleArguments(args, output)) return;
+  const startedAt = performance.now();
+  const rawRequest = parseJsonRequest(await readAll(input));
+  if (isStatusRequest(rawRequest)) {
+    writeJson(output, createStatusResponse());
+    return;
+  }
+  const request = parseRequest(rawRequest);
+  if (rawRequest.operation !== ANALYSIS_OPERATION) {
+    throw new Error(`unsupported operation ${String(rawRequest.operation)}`);
+  }
+  const result = analyzeSemanticQueries(request);
+  writeJson(output, responseFor(request, result, performance.now() - startedAt));
+};

package/src/file-identity.mjs

@@ -0,0 +1,11 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+export const canonicalFileIdentity = (fileName) => {
+  const absolutePath = path.normalize(path.resolve(fileName));
+  try {
+    return path.normalize(realpathSync.native(absolutePath));
+  } catch {
+    return absolutePath;
+  }
+};

package/src/generated-protocol.mjs

@@ -0,0 +1,27 @@
+// Generated from crates/api/type-aware-protocol.json. Do not edit.
+export const TYPE_AWARE_PROTOCOL = Object.freeze({
+  schema_version: 1,
+  wire_protocol_version: 6,
+  semantic_schema_version: 2,
+  analysis_operation: "semantic-queries",
+  status_operation: "status",
+  query_operations: ["symbol-use", "symbol-trace", "api-surface", "symbol-impact", "type-coupling"],
+  session_envelope_types: ["analyze", "shutdown"],
+  backend: {
+    family: "typescript-go",
+    version: "7.0.2",
+  },
+  sidecar: {
+    package: "fallow-type-aware",
+    version_source: "workspace-package",
+  },
+});
+export const WIRE_PROTOCOL_VERSION = TYPE_AWARE_PROTOCOL.wire_protocol_version;
+export const SEMANTIC_SCHEMA_VERSION = TYPE_AWARE_PROTOCOL.semantic_schema_version;
+export const ANALYSIS_OPERATION = TYPE_AWARE_PROTOCOL.analysis_operation;
+export const STATUS_OPERATION = TYPE_AWARE_PROTOCOL.status_operation;
+export const QUERY_OPERATIONS = Object.freeze(TYPE_AWARE_PROTOCOL.query_operations);
+export const SESSION_ENVELOPE_TYPES = Object.freeze(TYPE_AWARE_PROTOCOL.session_envelope_types);
+export const BACKEND_FAMILY = TYPE_AWARE_PROTOCOL.backend.family;
+export const BACKEND_VERSION = TYPE_AWARE_PROTOCOL.backend.version;
+export const SIDECAR_PACKAGE = TYPE_AWARE_PROTOCOL.sidecar.package;

package/src/graph-algorithms.mjs

@@ -0,0 +1,114 @@
+//! Deterministic graph algorithms shared by semantic capabilities.
+
+const compareText = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+
+const edgeAdjacency = (edges) => {
+  const adjacency = new Map();
+  for (const edge of edges) {
+    const source = edge.source.path;
+    const target = edge.target.path;
+    const targets = adjacency.get(source) ?? new Set();
+    targets.add(target);
+    adjacency.set(source, targets);
+  }
+  return adjacency;
+};
+
+const graphNodes = (adjacency) =>
+  [
+    ...new Set([
+      ...adjacency.keys(),
+      ...[...adjacency.values()].flatMap((targets) => [...targets]),
+    ]),
+  ].toSorted(compareText);
+
+const finishingOrder = (adjacency) => {
+  const visited = new Set();
+  const finished = [];
+  for (const root of graphNodes(adjacency)) {
+    if (visited.has(root)) continue;
+    visited.add(root);
+    const stack = [
+      { node: root, targets: [...(adjacency.get(root) ?? [])].toSorted(compareText), i: 0 },
+    ];
+    while (stack.length > 0) {
+      const frame = stack.at(-1);
+      if (frame.i >= frame.targets.length) {
+        finished.push(frame.node);
+        stack.pop();
+        continue;
+      }
+      const target = frame.targets[frame.i];
+      frame.i += 1;
+      if (visited.has(target)) continue;
+      visited.add(target);
+      stack.push({
+        node: target,
+        targets: [...(adjacency.get(target) ?? [])].toSorted(compareText),
+        i: 0,
+      });
+    }
+  }
+  return finished;
+};
+
+const reverseAdjacency = (adjacency) => {
+  const reversed = new Map(graphNodes(adjacency).map((node) => [node, new Set()]));
+  for (const [source, targets] of adjacency) {
+    targets.forEach((target) => reversed.get(target).add(source));
+  }
+  return reversed;
+};
+
+const stronglyConnectedComponents = (adjacency) => {
+  const reversed = reverseAdjacency(adjacency);
+  const visited = new Set();
+  const components = [];
+  for (const root of finishingOrder(adjacency).toReversed()) {
+    if (visited.has(root)) continue;
+    const component = [];
+    const pending = [root];
+    visited.add(root);
+    while (pending.length > 0) {
+      const node = pending.pop();
+      component.push(node);
+      for (const target of [...(reversed.get(node) ?? [])].toSorted(compareText).toReversed()) {
+        if (visited.has(target)) continue;
+        visited.add(target);
+        pending.push(target);
+      }
+    }
+    components.push(component.toSorted(compareText));
+  }
+  return components;
+};
+
+const componentCycle = (adjacency, component) => {
+  const allowed = new Set(component);
+  const start = component[0];
+  const queue = [...(adjacency.get(start) ?? [])]
+    .filter((target) => allowed.has(target))
+    .toSorted(compareText)
+    .map((target) => [start, target]);
+  const visited = new Set(queue.map((route) => route.at(-1)));
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const node = current.at(-1);
+    for (const target of [...(adjacency.get(node) ?? [])].toSorted(compareText)) {
+      if (target === start) return [...current, start];
+      if (!allowed.has(target) || visited.has(target)) continue;
+      visited.add(target);
+      queue.push([...current, target]);
+    }
+  }
+  return [];
+};
+
+export const findCycles = (edges) => {
+  const adjacency = edgeAdjacency(edges);
+  return stronglyConnectedComponents(adjacency)
+    .filter((component) => component.length > 1)
+    .map((component) => componentCycle(adjacency, component))
+    .filter((cycle) => cycle.length > 0)
+    .toSorted((left, right) => compareText(left.join("\0"), right.join("\0")));
+};

package/src/project-state.mjs

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { canonicalFileIdentity } from "./file-identity.mjs";
+import { relativePath } from "./semantic-identity.mjs";
+
+const INFERRED_PROJECT = "<inferred>";
+const compareText = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+const slash = (value) => value.split(path.sep).join("/");
+
+const blockingDiagnosticCount = (project) =>
+  project.program.getConfigFileParsingDiagnostics().length +
+  project.program.getProgramDiagnostics().length +
+  project.program.getSyntacticDiagnostics().length +
+  project.program.getBindDiagnostics().length;
+
+const configPath = (root, project) => {
+  const normalized = slash(project.configFileName);
+  if (normalized.endsWith("/dev/null/inferred")) return INFERRED_PROJECT;
+  return relativePath(root, project.configFileName) || path.basename(project.configFileName);
+};
+
+const normalizedConfigValue = (root, value) => {
+  if (Array.isArray(value)) return value.map((item) => normalizedConfigValue(root, item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .toSorted(([left], [right]) => compareText(left, right))
+        .map(([key, item]) => [key, normalizedConfigValue(root, item)]),
+    );
+  }
+  if (typeof value !== "string" || !path.isAbsolute(value)) return value;
+  const relative = path.relative(root, value);
+  return relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
+    ? slash(value)
+    : slash(relative || ".");
+};
+
+const stripJsonComments = (text) => {
+  let result = "";
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const current = text[index];
+    const next = text[index + 1];
+    if (inString) {
+      result += current;
+      if (escaped) escaped = false;
+      else if (current === "\\") escaped = true;
+      else if (current === '"') inString = false;
+      continue;
+    }
+    if (current === '"') {
+      inString = true;
+      result += current;
+      continue;
+    }
+    if (current === "/" && next === "/") {
+      result += "  ";
+      index += 2;
+      while (index < text.length && text[index] !== "\n") {
+        result += " ";
+        index += 1;
+      }
+      if (index < text.length) result += "\n";
+      continue;
+    }
+    if (current === "/" && next === "*") {
+      result += "  ";
+      index += 2;
+      while (index < text.length && !(text[index] === "*" && text[index + 1] === "/")) {
+        result += text[index] === "\n" ? "\n" : " ";
+        index += 1;
+      }
+      if (index < text.length) {
+        result += "  ";
+        index += 1;
+      }
+      continue;
+    }
+    result += current;
+  }
+  return result;
+};
+
+const stripTrailingCommas = (text) => {
+  let result = "";
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const current = text[index];
+    if (inString) {
+      result += current;
+      if (escaped) escaped = false;
+      else if (current === "\\") escaped = true;
+      else if (current === '"') inString = false;
+      continue;
+    }
+    if (current === '"') {
+      inString = true;
+      result += current;
+      continue;
+    }
+    if (current === ",") {
+      let lookahead = index + 1;
+      while (/\s/u.test(text[lookahead] ?? "")) lookahead += 1;
+      if (text[lookahead] === "}" || text[lookahead] === "]") continue;
+    }
+    result += current;
+  }
+  return result;
+};
+
+const readConfigDocument = (fileName) => {
+  try {
+    const text = readFileSync(fileName, "utf8");
+    return JSON.parse(stripTrailingCommas(stripJsonComments(text)));
+  } catch {
+    return undefined;
+  }
+};
+
+const resolveConfigDocument = (configFileName, specifier) => {
+  if (typeof specifier !== "string") return undefined;
+  if (!path.isAbsolute(specifier) && !specifier.startsWith(".")) return undefined;
+  const target = path.resolve(path.dirname(configFileName), specifier);
+  const candidates = path.extname(target)
+    ? [target]
+    : [path.join(target, "tsconfig.json"), `${target}.json`, target];
+  return candidates.find((candidate) => existsSync(candidate) && readConfigDocument(candidate));
+};
+
+const configDocumentClosure = (root, configFileName, seen = new Set()) => {
+  const document = readConfigDocument(configFileName);
+  if (!document) return null;
+  const canonical = canonicalFileIdentity(configFileName);
+  if (seen.has(canonical)) {
+    return { config: relativePath(root, canonical), cycle: true };
+  }
+  const nextSeen = new Set(seen).add(canonical);
+  const extensions = Array.isArray(document.extends) ? document.extends : [document.extends];
+  const referenced = Array.isArray(document.references) ? document.references : [];
+  const closure = (specifiers) =>
+    specifiers
+      .map((specifier) => resolveConfigDocument(configFileName, specifier))
+      .filter(Boolean)
+      .map((resolved) => configDocumentClosure(root, resolved, nextSeen))
+      .filter(Boolean)
+      .toSorted((left, right) => compareText(left.config, right.config));
+  return {
+    config: relativePath(root, canonical),
+    document: normalizedConfigValue(root, document),
+    extends: closure(extensions),
+    references: closure(referenced.map((reference) => reference?.path)),
+  };
+};
+
+const effectiveProjectConfigHash = (root, project) => {
+  const effective = {
+    config: configPath(root, project),
+    compiler_options: normalizedConfigValue(root, project.compilerOptions),
+    root_files: project.rootFiles
+      .map((fileName) => normalizedConfigValue(root, fileName))
+      .toSorted(compareText),
+    config_document: configDocumentClosure(root, project.configFileName),
+  };
+  return `sha256:${createHash("sha256").update(JSON.stringify(effective)).digest("hex")}`;
+};
+
+export const projectState = (root, project, source) => {
+  const diagnosticCount = blockingDiagnosticCount(project);
+  return {
+    project,
+    config: configPath(root, project),
+    effective_config_hash: effectiveProjectConfigHash(root, project),
+    source,
+    status: diagnosticCount === 0 ? "complete" : "unavailable",
+    reason_code: diagnosticCount === 0 ? null : "blocking-diagnostics",
+    blocking_diagnostic_count: diagnosticCount,
+    source_file_count: project.program.getSourceFileNames().length,
+    program_reused: false,
+    candidate_count: 0,
+    confirmed_used_count: 0,
+    contract_preserved_count: 0,
+    no_static_references_count: 0,
+    fix_eligible_count: 0,
+    unresolved_count: 0,
+    abstained_count: 0,
+  };
+};
+
+export const projectResult = ({ project: _project, ...state }) => state;