@milpa/comal 0.1.7 → 0.2.1

package/src/chrome-source-syntax.mjs

@@ -0,0 +1,93 @@
+import { Script } from 'node:vm';
+import { createHash } from 'node:crypto';
+import { open, realpath, lstat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { safeRelative } from './plugins/chrome-lab/project.mjs';
+
+const scopes = new WeakMap();
+const sha = bytes => createHash('sha256').update(bytes).digest('hex');
+const protectedPart = part => ['.git', '.comal', '.harness', '.ssh', 'node_modules'].includes(part) || /^\.env(?:\.|$)/i.test(part);
+
+// Native host metadata only. This supplies a dialect hint, never source access,
+// permission, code execution or a callback supplied by a resident/plugin.
+export function bindChromeSourceSyntax(workspace, sessionId, facts) {
+  if (typeof sessionId !== 'string' || !sessionId || !facts ||
+      Object.keys(facts).sort().join() !== 'directory,task_digest' ||
+      !/^[a-f0-9]{64}$/.test(facts.task_digest ?? '')) throw new Error('Invalid Chrome source syntax scope.');
+  const directory = safeRelative(facts.directory);
+  if (directory.split('/').some(protectedPart)) throw new Error('Protected Chrome source syntax scope.');
+  let sessions = scopes.get(workspace);
+  if (!sessions) scopes.set(workspace, sessions = new Map());
+  const token = Object.freeze({ directory, task_digest: facts.task_digest });
+  sessions.set(sessionId, token);
+  return {
+    dispose() { if (sessions.get(sessionId) === token) sessions.delete(sessionId); },
+  };
+}
+
+export function classicScriptSyntaxAdvice(source) {
+  if (typeof source !== 'string' || Buffer.byteLength(source) > 1048576) throw new Error('Expected bounded UTF-8 source.');
+  const advice = {
+    advisory: true, dialect: 'classic_script', parser: `node:${process.versions.node}/vm.Script`,
+    source_sha256: sha(source), execution: 'not_run', semantic_verification: 'unjudged',
+    scope: 'Node syntax only; Chrome compatibility and application behavior still require verification.',
+  };
+  try {
+    // Parsing never evaluates the candidate, including top-level expressions.
+    new Script(source, { filename: 'comal-content-script', displayErrors: true });
+    return { ...advice, status: 'parsed' };
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) return { ...advice, status: 'unavailable', reason: 'parser_unavailable' };
+    const location = /^comal-content-script:(\d+)(?::(\d+))?$/.exec(String(error.stack).split('\n')[0]);
+    return {
+      ...advice, status: 'syntax_error', line: location ? Number(location[1]) : null,
+      message: String(error.message).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 240),
+      next_action: 'Correct this candidate source before publishing; the file write itself is still recorded separately.',
+    };
+  }
+}
+
+// Only a currently declared classic content script receives parser feedback.
+// Missing/invalid/changed manifests, ESM workers and unrelated files are unknown,
+// not fabricated classic-script syntax errors. No raw manifest/code is returned.
+export async function chromeSourceSyntaxAdvice(workspace, { sessionId, file, source }) {
+  const sessions = scopes.get(workspace), scope = sessions?.get(sessionId);
+  if (!scope) return undefined;
+  let handle;
+  try {
+    const directory = path.resolve(workspace.cwd, scope.directory);
+    const relative = path.relative(directory, file);
+    if (!relative || relative === '..' || relative === 'manifest.json' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) return undefined;
+    if (!workspace.inside(directory) || await realpath(directory) !== directory) return undefined;
+    const manifestFile = path.join(directory, 'manifest.json');
+    if (await workspace.resolve(manifestFile) !== manifestFile || await realpath(manifestFile) !== manifestFile) return undefined;
+    handle = await open(manifestFile, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.size > 65536n) return undefined;
+    // A pre-stat cannot bound readFile when an ordinary file grows afterwards.
+    // Read at most64KiB plus one overflow byte, even across short reads/growth.
+    const buffer = Buffer.alloc(65537); let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    const bytes = buffer.subarray(0, length), after = await handle.stat({ bigint: true }), named = await lstat(manifestFile, { bigint: true });
+    if (length > 65536 || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeNs !== after.mtimeNs ||
+        named.isSymbolicLink() || named.dev !== after.dev || named.ino !== after.ino || named.size !== after.size || named.mtimeNs !== after.mtimeNs ||
+        BigInt(bytes.length) !== before.size || await realpath(manifestFile) !== manifestFile || sessions.get(sessionId) !== scope) return undefined;
+    const manifest = JSON.parse(bytes.toString('utf8'));
+    if (manifest?.manifest_version !== 3 || !Array.isArray(manifest.content_scripts)) return undefined;
+    const packaged = relative.split(path.sep).join('/');
+    const declared = manifest.content_scripts.some(group => group && Array.isArray(group.js) && group.js.some(value => {
+      try { return safeRelative(value) === packaged; } catch { return false; }
+    }));
+    if (!declared) return undefined;
+    return { ...classicScriptSyntaxAdvice(source), task_digest: scope.task_digest, manifest_sha256: sha(bytes) };
+  } catch {
+    // An advisory availability failure must not convert an authorized Write/Edit
+    // into a failure or change its source/permission/recovery semantics.
+    return undefined;
+  } finally { await handle?.close().catch(() => {}); }
+}