@tech-leads-club/harness-toolkit 0.2.1

package/src/core/comment-policy/comment-syntax.catalog.ts

@@ -0,0 +1,310 @@
+import type { CommentSyntaxEntry } from "./comment-syntax.types.ts";
+
+/**
+ * why: the whole per-language knowledge of the comment gate, as one table. It replaced three hand-written regexes
+ * and a ten-extension list; adding a language is an entry here and nothing else
+ * ([/decisions/ad-058.md](/decisions/ad-058.md)).
+ *
+ * invariant: a module rather than a JSON file read at runtime. A hook is a process, so a data file would be one
+ * more read on every invocation and one more path to resolve differently under Bun, under `dist/` and under a
+ * hermetic test home — which is exactly how the first version of this broke its own suite. Bundled, it costs
+ * nothing and behaves identically everywhere.
+ *
+ * invariant: shapes follow the `comments` block of an editor language-configuration file, which is the maintained
+ * machine-readable form of this knowledge. `middle` is the continuation prefix a block conventionally carries.
+ */
+export const COMMENT_SYNTAX: readonly CommentSyntaxEntry[] = [
+  {
+    id: "typescript",
+    extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "python",
+    extensions: [".py", ".pyi", ".pyw"],
+    line: ["#"],
+    block: [
+      ['"""', '"""'],
+      ["'''", "'''"],
+    ],
+    middle: [],
+  },
+  {
+    id: "ruby",
+    extensions: [".rb", ".rake", ".gemspec"],
+    line: ["#"],
+    block: [["=begin", "=end"]],
+    middle: [],
+  },
+  {
+    id: "shell",
+    extensions: [".sh", ".bash", ".zsh", ".ksh", ".fish"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "go",
+    extensions: [".go"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "rust",
+    extensions: [".rs"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "java",
+    extensions: [".java"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "kotlin",
+    extensions: [".kt", ".kts"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "swift",
+    extensions: [".swift"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "c",
+    extensions: [".c", ".h"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "cpp",
+    extensions: [".cc", ".cpp", ".cxx", ".hpp", ".hh", ".hxx"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "csharp",
+    extensions: [".cs"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "php",
+    extensions: [".php"],
+    line: ["//", "#"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "scala",
+    extensions: [".scala", ".sc"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "dart",
+    extensions: [".dart"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "elixir",
+    extensions: [".ex", ".exs"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "erlang",
+    extensions: [".erl", ".hrl"],
+    line: ["%"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "haskell",
+    extensions: [".hs"],
+    line: ["--"],
+    block: [["{-", "-}"]],
+    middle: [],
+  },
+  {
+    id: "lua",
+    extensions: [".lua"],
+    line: ["--"],
+    block: [["--[[", "]]"]],
+    middle: [],
+  },
+  {
+    id: "sql",
+    extensions: [".sql"],
+    line: ["--"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "css",
+    extensions: [".css", ".scss", ".sass", ".less"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "yaml",
+    extensions: [".yaml", ".yml"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "toml",
+    extensions: [".toml"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "ini",
+    extensions: [".ini", ".cfg", ".conf", ".properties"],
+    line: [";", "#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "dockerfile",
+    extensions: [".dockerfile", "dockerfile"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "makefile",
+    extensions: [".mk", "makefile"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "terraform",
+    extensions: [".tf", ".tfvars"],
+    line: ["#", "//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "powershell",
+    extensions: [".ps1", ".psm1", ".psd1"],
+    line: ["#"],
+    block: [["<#", "#>"]],
+    middle: [],
+  },
+  {
+    id: "perl",
+    extensions: [".pl", ".pm"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "r",
+    extensions: [".r"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "julia",
+    extensions: [".jl"],
+    line: ["#"],
+    block: [["#=", "=#"]],
+    middle: [],
+  },
+  {
+    id: "vue",
+    extensions: [".vue", ".svelte"],
+    line: ["//"],
+    block: [
+      ["/*", "*/"],
+      ["<!--", "-->"],
+    ],
+    middle: ["*"],
+  },
+  {
+    id: "html",
+    extensions: [".html", ".htm", ".xml", ".xhtml"],
+    line: [],
+    block: [["<!--", "-->"]],
+    middle: [],
+  },
+  {
+    id: "graphql",
+    extensions: [".graphql", ".gql"],
+    line: ["#"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "protobuf",
+    extensions: [".proto"],
+    line: ["//"],
+    block: [["/*", "*/"]],
+    middle: ["*"],
+  },
+  {
+    id: "zig",
+    extensions: [".zig"],
+    line: ["//"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "clojure",
+    extensions: [".clj", ".cljs", ".cljc", ".edn"],
+    line: [";"],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "ocaml",
+    extensions: [".ml", ".mli"],
+    line: [],
+    block: [["(*", "*)"]],
+    middle: ["*"],
+  },
+  {
+    id: "fsharp",
+    extensions: [".fs", ".fsi", ".fsx"],
+    line: ["//"],
+    block: [["(*", "*)"]],
+    middle: ["*"],
+  },
+  {
+    id: "vim",
+    extensions: [".vim"],
+    line: ['"'],
+    block: [],
+    middle: [],
+  },
+  {
+    id: "tex",
+    extensions: [".tex", ".sty", ".cls"],
+    line: ["%"],
+    block: [],
+    middle: [],
+  },
+];

package/src/core/comment-policy/comment-syntax.store.ts

@@ -0,0 +1,65 @@
+import { COMMENT_SYNTAX } from "./comment-syntax.catalog.ts";
+import type { CommentSyntax, CommentSyntaxEntry } from "./comment-syntax.types.ts";
+
+/**
+ * why: the layer between the catalog's shape and the question the scanner asks. Everything the scanner knows
+ * about languages arrives through `syntaxFor`, so the table can grow, be reordered or be regenerated from an
+ * upstream language-configuration set without the scanner changing
+ * ([/decisions/ad-058.md](/decisions/ad-058.md)).
+ */
+export function buildIndex(entries: readonly CommentSyntaxEntry[]): Map<string, CommentSyntax> {
+  const byKey = new Map<string, CommentSyntax>();
+  for (const entry of entries) {
+    const syntax: CommentSyntax = { line: entry.line, block: entry.block, middle: entry.middle };
+    for (const extension of entry.extensions) {
+      byKey.set(extension.toLowerCase(), syntax);
+    }
+  }
+  return byKey;
+}
+
+const INDEX = buildIndex(COMMENT_SYNTAX);
+
+/**
+ * invariant: the longest matching extension wins, so a two-part extension cannot be shadowed by its own tail. A
+ * name with no dot is matched by the whole name, which is how `Dockerfile` and `Makefile` are reached.
+ *
+ * invariant: an unknown extension returns `null`, never a guess. Assuming a delimiter for an unrecognised
+ * language is how `#` came to mean "comment" in TypeScript, where it starts a private field.
+ */
+export function lookupSyntax(file: string, index = INDEX): CommentSyntax | null {
+  const lower = file.toLowerCase().replace(/\\/g, "/");
+  const name = lower.slice(lower.lastIndexOf("/") + 1);
+  const direct = index.get(name);
+  if (direct) {
+    return direct;
+  }
+  let best: CommentSyntax | null = null;
+  let bestLength = 0;
+  for (const [extension, syntax] of index) {
+    if (extension.startsWith(".") && name.endsWith(extension) && extension.length > bestLength) {
+      best = syntax;
+      bestLength = extension.length;
+    }
+  }
+  return best;
+}
+
+export function syntaxFor(file: string): CommentSyntax | null {
+  return lookupSyntax(file);
+}
+
+/** why: the operator needs the coverage gap named. A language nobody listed is a rail that silently passes. */
+export function unknownExtensions(files: readonly string[]): string[] {
+  const unknown = new Set<string>();
+  for (const file of files) {
+    if (lookupSyntax(file) === null) {
+      const name = file.toLowerCase().replace(/\\/g, "/").split("/").pop() ?? file;
+      const dot = name.lastIndexOf(".");
+      unknown.add(dot > 0 ? name.slice(dot) : name);
+    }
+  }
+  return [...unknown].sort();
+}
+
+export const KNOWN_EXTENSION_COUNT = INDEX.size;

package/src/core/comment-policy/comment-syntax.types.ts

@@ -0,0 +1,24 @@
+/**
+ * The domain's own vocabulary for "how does this file write a comment". The scanner asks that question and gets
+ * this answer; it knows nothing about extensions, languages or delimiters beyond what is in here.
+ */
+export type CommentSyntax = {
+  /** Prefixes that start a comment running to end of line. */
+  line: readonly string[];
+  /** Open/close pairs. A pair whose open and close are equal is a symmetric fence, like a Python docstring. */
+  block: readonly (readonly [string, string])[];
+  /**
+   * Prefixes a continuation line inside a block conventionally carries — `*` in the C family. Without it a
+   * multi-line doc block reads as one comment followed by unrelated lines, and a marker on its first line stops
+   * covering the rest of it.
+   */
+  middle: readonly string[];
+};
+
+export type CommentSyntaxEntry = CommentSyntax & {
+  id: string;
+  /** Extensions including the dot, or a bare filename for the ones that have none (`Dockerfile`, `Makefile`). */
+  extensions: readonly string[];
+};
+
+export const NO_COMMENT_SYNTAX: CommentSyntax = { line: [], block: [], middle: [] };