@starci/eslint-canon-be 1.8.0 → 2.0.0

package/runtime/scripts/lib/hfs-view.mjs

@@ -0,0 +1,68 @@
+// hfs-view.mjs - the frozen view of one repository's HFS slots that the lint factories hand their rules
+// (`settings.starci.hfs`). Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file in their
+// runtime/ bundle (packages/hfs/scripts/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
+// architecture machine and `hfs check` use, and never tests a path with a regular expression of its own.
+import path from 'node:path';
+import { allowsFile } from './hfs-allows.mjs';
+import { openHfs } from './hfs-slots.mjs';
+
+const posix = (p) => String(p).replace(/\\/g, '/');
+const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
+
+/**
+ * The view rules read, over an opened resolver.
+ *
+ * @param {object} opened - The result of `openHfs` (manifest, repo and resolver methods).
+ * @param {string} repoRoot - The absolute repository root.
+ * @returns {object} The frozen view: profile, apps, connections, ruleParams, relative, classify, slotOf, tierOf, ownerOf, slot.
+ */
+export function hfsView(opened, repoRoot) {
+  const rel = (file) => {
+    const text = posix(file);
+    if (!isAbsoluteAny(text)) return text.replace(/^\.\//, '');
+    return posix(path.relative(repoRoot, file));
+  };
+  const slotCache = new Map();
+  const classify = (file) => {
+    const key = rel(file);
+    if (!slotCache.has(key)) slotCache.set(key, opened.classifyPath(key));
+    return slotCache.get(key);
+  };
+  return Object.freeze({
+    repoRoot,
+    profile: opened.repo.profile,
+    apps: opened.repo.apps,
+    connections: opened.repo.connections,
+    ruleParams: opened.ruleParams(),
+    /** The repository-relative, forward-slash form of a linted filename. */
+    relative: rel,
+    /** The classification of a file: `{ slot, tier, owner?, bindings? ... }` or a no-slot status. */
+    classify,
+    /** The slot id that owns a file, or null when no slot does. */
+    slotOf: (file) => classify(file).slot ?? null,
+    /** The tier of a file, or null. */
+    tierOf: (file) => opened.tierOf(rel(file)) ?? null,
+    /** The owner root of a file, or null. */
+    ownerOf: (file) => opened.ownerOf(rel(file))?.root ?? null,
+    /** What the slot that owns a file says about it: `{ slot, root, relative, allowed, entry?, forbiddenBy?, allows }`, or null when the slot names no `allows`. */
+    allows: (file) => allowsFile(opened, rel(file)),
+    /** A slot definition by id. */
+    slot: (id) => opened.slot(id),
+  });
+}
+
+/**
+ * The view of the repository on disk whose root is `repoRoot`, against the manifest under `runtimeRoot`.
+ *
+ * @param {{ runtimeRoot: string, repoRoot: string }} input - Where the manifest copy lives and the repository root.
+ * @returns {object} The frozen view.
+ */
+export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root: runtimeRoot, repoRoot }), repoRoot);
+
+/**
+ * The view of an in-memory declaration (rule tests): no file is read except the manifest.
+ *
+ * @param {{ runtimeRoot: string, declaration: object, repoRoot: string }} input - Manifest root, hfs.json object, linted root.
+ * @returns {object} The frozen view.
+ */
+export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot }) => hfsView(openHfs({ root: runtimeRoot, declaration }), repoRoot);

package/runtime/scripts/lib/language.mjs

@@ -0,0 +1,107 @@
+// language.mjs - the one home of "is this text English?" for source, comments, tests and docs (HFS_LANGUAGE_NOT_ENGLISH,
+// BE_SOURCE_FORM, FE_SOURCE_FORM). Shared by the architecture machine (docs) and by both lint canons (each ships a byte
+// copy in its runtime/ bundle, kept by packages/hfs/scripts/sync-runtime.mjs).
+//
+// Detection is structural on characters, never a word list: the letters Vietnamese adds to the Latin alphabet (a-breve, a-circumflex,
+// d-stroke, e-circumflex, o-circumflex, o-horn, u-horn) and every vowel carrying a tone mark. Text is folded to NFC first, so a
+// decomposed spelling (base letter + combining mark) is caught exactly like the precomposed one, and a loanword such as
+// `naive`, `facade` or `Muller` (no tone mark, no Vietnamese letter) is never a hit.
+import path from 'node:path';
+
+/** One Vietnamese letter, precomposed (NFC): the Vietnamese-specific base letters, tone-marked vowels and the Latin Extended Additional block. */
+export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìíò-õùúýĂăĐđĨĩŨũƠơƯưẠ-ỿ]/;
+
+/** Whether `text` holds a Vietnamese letter, in NFC or NFD spelling. */
+export const hasSecondLanguage = (text) => typeof text === 'string' && SECOND_LANGUAGE_LETTER.test(text.normalize('NFC'));
+
+/** Every line of `text` with a Vietnamese letter: `[{ line, column }]`, both 1-based. */
+export function secondLanguageHits(text) {
+  const hits = [];
+  String(text).split(/\r?\n/).forEach((raw, index) => {
+    const match = SECOND_LANGUAGE_LETTER.exec(raw.normalize('NFC'));
+    if (match) hits.push({ line: index + 1, column: match.index + 1 });
+  });
+  return hits;
+}
+
+/**
+ * The Vietnamese fields of one failure-code entry: the operator text the owner mandated for the failure-code catalog
+ * (scripts/checks/failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.
+ */
+export const FAILURE_CODE_VIETNAMESE_FIELDS = Object.freeze(['title_vi', 'meaning_vi', 'nextStep_vi', 'causes_vi']);
+
+/**
+ * The fields of a document that carry deliberate Vietnamese text, keyed by file: a declared field-level exception of that file's
+ * typed content, never a path pattern over content. `fields` are block keys (the key's own value and its list items are exempt);
+ * `flowFields` are keys inside an inline flow map (`{ vi: ..., en: ... }`), where only that key's value is exempt. A Vietnamese
+ * value under any other key of the same file is still a finding.
+ *  - modules/kernel/failure-codes.yaml: the operator text the owner mandated for the failure-code catalog.
+ *  - modules/ops/_labels.yaml: the op-label catalogue, one `{ vi, en }` pair per op (the `vi` field is the localized label).
+ *  - modules/goal/archetypes.yaml: the Vietnamese phrase lexicons matched against owner input (the signal phrase sets, and the
+ *    phrase lists of the archetype recognisers).
+ */
+export const DECLARED_VIETNAMESE_FIELDS = Object.freeze({
+  'modules/kernel/failure-codes.yaml': Object.freeze({ fields: FAILURE_CODE_VIETNAMESE_FIELDS }),
+  'modules/ops/_labels.yaml': Object.freeze({ flowFields: Object.freeze(['vi']) }),
+  'modules/goal/archetypes.yaml': Object.freeze({
+    fields: Object.freeze([
+      'buildIntent', 'canonIntent', 'e2eIntent', 'uatIntent', 'proofNegation', 'integrationIntent', 'integrationNegation', 'brandIntent',
+      'phrases', 'requires', 'excludes', 'backend', 'frontend', 'package',
+    ]),
+  }),
+});
+
+/**
+ * The slots whose files may carry another language, and why: a catalog is product copy in two languages, and an i18n
+ * fixture reproduces a real localized string a parser or formatter must accept. Placement is the whole marker - there is no
+ * comment pragma and no path pattern. The slots are declared in knowledge/hfs/slots.yaml.
+ */
+export const LOCALIZED_TEXT_SLOTS = Object.freeze([
+  'be.domain.messages', 'be.feature.messages', 'be.tests.fixtures.i18n',
+  'fe.modules.i18n', 'fe.package.i18n',
+]);
+
+/** Whether a document (Markdown or YAML) of `slot` is exempt: only catalogue and fixture DATA (YAML) is; Markdown is prose and never is. */
+export const isLocalizedDataFile = (rel, slot) => LOCALIZED_TEXT_SLOTS.includes(slot) && /\.ya?ml$/.test(rel);
+
+/**
+ * The key each line of a YAML text belongs to: a `key:` line owns itself, and every deeper-indented line after it (a list item,
+ * a folded block, a wrapped scalar) belongs to the same key. A line at or above the key's indent that is not a key belongs to none.
+ */
+export function yamlKeyOfEachLine(text) {
+  let key = null;
+  let keyIndent = -1;
+  return String(text).split(/\r?\n/).map((raw) => {
+    if (raw.trim() === '') return key;
+    const indent = raw.length - raw.trimStart().length;
+    const own = /^(\s*(?:-\s+)?)([A-Za-z_][\w-]*)\s*:(?:\s|$)/.exec(raw);
+    if (own) { key = own[2]; keyIndent = own[1].length; return key; }
+    // a list item may sit at the key's own indent (`key:` then `- item` at the same column)
+    if (indent > keyIndent || (indent === keyIndent && /^\s*-\s/.test(raw))) return key;
+    key = null;
+    keyIndent = -1;
+    return null;
+  });
+}
+
+/** The Vietnamese hits of a document, minus the declared field-level exceptions of `rel` (a repository-relative POSIX path). */
+export function documentLanguageHits(rel, text) {
+  const declared = DECLARED_VIETNAMESE_FIELDS[rel];
+  const hits = secondLanguageHits(text);
+  if (!declared) return hits;
+  const keys = yamlKeyOfEachLine(text);
+  const lines = String(text).split(/\r?\n/);
+  return hits.filter((hit) => {
+    if (declared.fields?.includes(keys[hit.line - 1])) return false;
+    if (!declared.flowFields) return true;
+    // an inline flow map: drop the declared fields' values and judge what is left of the line
+    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(`\\b${field}\\s*:\\s*[^,}]*`, 'g'), ''), lines[hit.line - 1]);
+    return hasSecondLanguage(rest);
+  });
+}
+
+/** The file extensions of a prose document (Markdown and YAML). */
+export const DOCUMENT_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml']);
+
+/** Whether `rel` is a document a language check reads. */
+export const isDocument = (rel) => DOCUMENT_EXTENSIONS.includes(path.posix.extname(rel));

package/runtime/scripts/lib/path-key.mjs

@@ -0,0 +1,17 @@
+// path-key.mjs — spelling and comparing paths the way this host's filesystem does.
+import path from 'node:path';
+
+const WIN = process.platform === 'win32';
+
+/** `p` with every backslash turned into a forward slash; null and undefined read as ''. */
+export const slash = (p) => String(p ?? '').replaceAll('\\', '/');
+/** A relative path in git's spelling: forward slashes, no leading './'. */
+export const posixPath = (p) => slash(p).replace(/^\.\//, '');
+/** Whether posix `file` is `prefix` itself or under it (`file === prefix || file` starts with `prefix/`). */
+export const sameOrUnder = (file, prefix) => file === prefix || file.startsWith(`${prefix}/`);
+/** `p` case-folded where the filesystem ignores case (Windows). */
+export const foldCase = (p) => (WIN ? p.toLowerCase() : p);
+/** Whether two spellings name the same path on this host's filesystem. */
+export const samePath = (a, b) => foldCase(a) === foldCase(b);
+/** A path's comparable identity: absolute, forward slashes, no trailing slash, case-folded on Windows. */
+export const pathKey = (p) => foldCase(slash(path.resolve(p)).replace(/\/+$/, ''));

package/runtime/scripts/lib/recorded-lines.mjs

@@ -0,0 +1,27 @@
+// recorded-lines.mjs - the one home of the file-size ratchet's arithmetic (R20 HFS_SIZE_GROWTH), shared by the back-end
+// and front-end lint canons (each ships a byte copy in its runtime/ bundle, kept by packages/hfs/scripts/sync-runtime.mjs).
+import path from 'node:path';
+import { runGit } from './git.mjs';
+
+/** The line count of a text; a trailing newline does not open a line. */
+export const lineCount = (text) => {
+  const lines = String(text).split(/\r?\n/);
+  return lines.at(-1) === '' ? lines.length - 1 : lines.length;
+};
+
+/** The line count above which a file may not grow: the soft budget when `hardGrowth` holds, else no limit. */
+export const hardGrowthLines = ({ soft, hardGrowth }) => (hardGrowth ? soft : Number.POSITIVE_INFINITY);
+
+/**
+ * The line count of a file at a git revision, or null when the file did not exist there or git is absent.
+ *
+ * @param {string} filename - Absolute path of the file.
+ * @param {string} ref - The revision, `HEAD` by default (the parent of the commit being made).
+ * @returns {number | null} The recorded line count.
+ */
+export const recordedLines = (filename, ref = 'HEAD') => {
+  const r = runGit(['show', `${ref}:./${path.basename(filename)}`], { dir: path.dirname(filename), maxBuffer: 64 * 1024 * 1024 });
+  // no repository, no such revision, or a new file: all mean there is no recorded size to compare with
+  if (r.error || r.status !== 0) return null;
+  return lineCount(r.stdout);
+};