tackbox 0.1.0

package/js/rules/valid-error-report.js

@@ -0,0 +1,99 @@
+const {
+  REPORTER_FULL, REPORTER_SYNTH,
+  tier1ReporterName, isTier1Notify, isStaticString, staticStringValue, isTestFile,
+} = require('./_shared')
+
+const MIN = 15
+const MAX = 200
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'reporter/notify args: static 15-200 msg, cause non-null, tags non-empty, dedupKey present (notify shares the msg/cause/tags/dedupKey shape - D007/D008)' },
+    messages: {
+      noArgs: '{{name}} requires at least (msg, cause)',
+      msgNotStatic: '{{name}}: first arg (msg) must be a static string literal (no template interpolation)',
+      msgTooShort: '{{name}}: msg is {{len}} chars, must be at least {{min}}',
+      msgTooLong: '{{name}}: msg is {{len}} chars, must be at most {{max}}',
+      causeMissing: '{{name}}: second arg (cause) must be present and not null/undefined',
+      tagsEmpty: '{{name}}: tags arg must not be {} — drop the arg or supply real tags',
+      dedupMissing: '{{name}}: dedupKey is required (last arg) — spec mandates per-site dedupKey',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    return {
+      CallExpression(node) {
+        let name = tier1ReporterName(context, node)
+        // notify is not a reporter (never credits a swallow), but its user-lane
+        // msg must be a static literal (D007) and it carries the full
+        // (msg, cause, tags, dedupKey) shape, so it is validated like one.
+        let notifyVerb = false
+        if (!name) {
+          if (isTier1Notify(context, node)) {
+            name = 'notify'
+            notifyVerb = true
+          } else {
+            return
+          }
+        }
+
+        const args = node.arguments
+        if (args.length < 1) {
+          context.report({ node, messageId: 'noArgs', data: { name } })
+          return
+        }
+
+        const msg = args[0]
+        if (!isStaticString(msg)) {
+          context.report({ node: msg, messageId: 'msgNotStatic', data: { name } })
+        } else {
+          const v = staticStringValue(msg)
+          if (v.length < MIN) {
+            context.report({ node: msg, messageId: 'msgTooShort', data: { name, len: v.length, min: MIN } })
+          } else if (v.length > MAX) {
+            context.report({ node: msg, messageId: 'msgTooLong', data: { name, len: v.length, max: MAX } })
+          }
+        }
+
+        const isFull = REPORTER_FULL.has(name) || notifyVerb
+        const isSynth = REPORTER_SYNTH.has(name)
+
+        // (msg, cause, tags, dedupKey) for full reporters.
+        if (isFull) {
+          if (args.length < 2) {
+            context.report({ node, messageId: 'causeMissing', data: { name } })
+            return
+          }
+          const cause = args[1]
+          if (cause.type === 'Literal' && (cause.value === null || cause.value === undefined)) {
+            context.report({ node: cause, messageId: 'causeMissing', data: { name } })
+          }
+          if (cause.type === 'Identifier' && cause.name === 'undefined') {
+            context.report({ node: cause, messageId: 'causeMissing', data: { name } })
+          }
+          const tags = args[2]
+          if (tags && tags.type === 'ObjectExpression' && tags.properties.length === 0) {
+            context.report({ node: tags, messageId: 'tagsEmpty', data: { name } })
+          }
+          if (args.length < 4) {
+            context.report({ node, messageId: 'dedupMissing', data: { name } })
+          }
+          return
+        }
+
+        // (msg, tags, dedupKey) for synth reporters.
+        if (isSynth) {
+          const tags = args[1]
+          if (tags && tags.type === 'ObjectExpression' && tags.properties.length === 0) {
+            context.report({ node: tags, messageId: 'tagsEmpty', data: { name } })
+          }
+          if (args.length < 3) {
+            context.report({ node, messageId: 'dedupMissing', data: { name } })
+          }
+        }
+      },
+    }
+  },
+}

package/js/tests/eslint-wrapper.test.js

@@ -0,0 +1,53 @@
+const path = require('node:path')
+const os = require('node:os')
+const fs = require('node:fs')
+const { spawnSync } = require('node:child_process')
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+
+const WRAPPER = path.resolve(__dirname, '..', '..', 'bin', 'tackbox-eslint.js')
+
+// An empty catch defeated by an inline eslint-disable. The hermetic wrapper must
+// ignore the directive (allowInlineConfig: false) so the swallow still fails the
+// run: an inline disable is an uninventoried, ungated bypass of every JS rule,
+// invisible to `tackbox escapes` and the approval gate.
+const DISABLED_SWALLOW = [
+  'function handler() {',
+  '  try {',
+  '    doThing()',
+  '  // eslint-disable-next-line tackbox/no-swallow-catch',
+  '  } catch (e) {',
+  '  }',
+  '}',
+  '',
+].join('\n')
+
+function inTmpDir(body) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tackbox-eslint-'))
+  fs.writeFileSync(path.join(dir, 'bad.js'), DISABLED_SWALLOW)
+  try {
+    return body(dir)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+function runWrapper(dir, args) {
+  return spawnSync('node', [WRAPPER, ...args, 'bad.js'], { cwd: dir, encoding: 'utf8' })
+}
+
+test('inline eslint-disable cannot silence a swallow (default mode)', () => {
+  inTmpDir(dir => {
+    const r = runWrapper(dir, [])
+    assert.equal(r.status, 1, r.stdout + r.stderr)
+    assert.match(r.stdout, /no-swallow-catch/)
+  })
+})
+
+test('inline eslint-disable cannot silence a swallow (--machine mode)', () => {
+  inTmpDir(dir => {
+    const r = runWrapper(dir, ['--machine'])
+    assert.equal(r.status, 1, r.stdout + r.stderr)
+    assert.match(r.stdout, /no-swallow-catch/)
+  })
+})

package/js/tests/mdlint-wrapper.test.js

@@ -0,0 +1,85 @@
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawnSync } = require('node:child_process')
+const { mkdtempSync, writeFileSync, rmSync } = require('node:fs')
+const { tmpdir } = require('node:os')
+const path = require('node:path')
+
+const WRAPPER = path.resolve(__dirname, '..', '..', 'bin', 'tackbox-mdlint.js')
+
+function withTmp(fn) {
+  const dir = mkdtempSync(path.join(tmpdir(), 'tackbox-mdlint-'))
+  try { return fn(dir) } finally { rmSync(dir, { recursive: true, force: true }) }
+}
+
+function lintInTmp(dir, file) {
+  return spawnSync('node', [WRAPPER, file], { cwd: dir, encoding: 'utf8' })
+}
+
+test('ignores consumer .markdownlint.json that disables defaults', () => {
+  withTmp(dir => {
+    writeFileSync(path.join(dir, '.markdownlint.json'), '{"default": false}')
+    writeFileSync(path.join(dir, 'bad.md'), '# hi\n\nrocket: \u{1F680}\n')
+    const r = lintInTmp(dir, 'bad.md')
+    assert.equal(r.status, 1, r.stdout + r.stderr)
+    assert.match(r.stdout, /no-non-ascii/)
+    assert.match(r.stdout, /U\+1F680/)
+  })
+})
+
+test('rejects inline markdownlint-disable for the ASCII rule', () => {
+  withTmp(dir => {
+    const md = [
+      '# hi',
+      '',
+      '<!-- markdownlint-disable no-non-ascii -->',
+      '',
+      'still flagged: \u{2014}',
+      '',
+    ].join('\n')
+    writeFileSync(path.join(dir, 'bad.md'), md)
+    const r = lintInTmp(dir, 'bad.md')
+    assert.equal(r.status, 1, r.stdout + r.stderr)
+    assert.match(r.stdout, /U\+2014/)
+  })
+})
+
+test('exits 0 on clean ASCII file', () => {
+  withTmp(dir => {
+    writeFileSync(path.join(dir, 'ok.md'), '# clean\n\nplain ASCII only.\n')
+    const r = lintInTmp(dir, 'ok.md')
+    assert.equal(r.status, 0, r.stdout + r.stderr)
+    assert.equal(r.stdout, '')
+  })
+})
+
+// End-to-end (default rules + noInlineConfig): the lang marker survives the
+// real CLI path, not just the rule unit tests.
+
+const PRIVET = '\u{41F}\u{440}\u{438}\u{432}\u{435}\u{442}' // "Privet" (hello)
+const MIR = '\u{43C}\u{438}\u{440}' // "mir" (world)
+
+test('ru marker: Russian prose passes the real wrapper clean', () => {
+  withTmp(dir => {
+    writeFileSync(
+      path.join(dir, 'ru.md'),
+      '<!-- tackbox: lang=ru personal repo -->\n\n# notes\n\n' + PRIVET + ' \u{2014} ' + MIR + '.\n'
+    )
+    const r = lintInTmp(dir, 'ru.md')
+    assert.equal(r.status, 0, r.stdout + r.stderr)
+    assert.equal(r.stdout, '')
+  })
+})
+
+test('ru marker still flags an emoji, not the Cyrillic', () => {
+  withTmp(dir => {
+    writeFileSync(
+      path.join(dir, 'ru.md'),
+      '<!-- tackbox: lang=ru note -->\n\n# notes\n\n' + PRIVET + ' \u{1F680}\n'
+    )
+    const r = lintInTmp(dir, 'ru.md')
+    assert.equal(r.status, 1, r.stdout + r.stderr)
+    assert.match(r.stdout, /U\+1F680/)
+    assert.doesNotMatch(r.stdout, /U\+41F/)
+  })
+})

package/js/tests/no-non-ascii.test.js

@@ -0,0 +1,124 @@
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const { lint } = require('markdownlint/promise')
+const rule = require('../markdownlint-rules/no-non-ascii')
+
+async function run(markdown) {
+  const out = await lint({
+    strings: { 'in.md': markdown },
+    config: { default: false, 'no-non-ascii': true },
+    customRules: [rule],
+  })
+  return out['in.md']
+}
+
+test('passes on pure ASCII content', async () => {
+  const errs = await run([
+    '# heading',
+    '',
+    'A paragraph with - dash, "quotes", `code`, and 0x7f end.',
+    '',
+    '```bash',
+    'echo hi',
+    '```',
+  ].join('\n'))
+  assert.equal(errs.length, 0)
+})
+
+test('flags assorted non-ASCII (em-dash, curly, Cyrillic, box)', async () => {
+  const errs = await run('em \u{2014} curly \u{201C}x\u{201D} hi \u{43F}\n\u{251C}\n')
+  const hexes = errs.map(e => e.errorDetail.match(/U\+([0-9A-F]+)/)[1])
+  assert.deepEqual(hexes, ['2014', '201C', '201D', '43F', '251C'])
+})
+
+test('flags non-ASCII inside fenced code blocks', async () => {
+  const errs = await run('```text\nhello \u{2014} world\n```\n')
+  assert.equal(errs.length, 1)
+  assert.equal(errs[0].lineNumber, 2)
+})
+
+test('reports column position and astral codepoints', async () => {
+  const errs = await run('abc\u{1F680}xyz\n')
+  assert.equal(errs.length, 1)
+  assert.match(errs[0].errorDetail, /U\+1F680/)
+  assert.deepEqual(errs[0].errorRange, [4, 2])
+})
+
+// -- lang marker ----------------------------------------------------------
+
+// Cyrillic building blocks, written as \u escapes so this source stays ASCII.
+const PRIVET = '\u{41F}\u{440}\u{438}\u{432}\u{435}\u{442}' // "Privet" (hello)
+const MIR = '\u{43C}\u{438}\u{440}' // "mir" (world)
+
+function detailHexes(errs) {
+  return errs.map(e => e.errorDetail.match(/U\+([0-9A-F]+)/)[1])
+}
+
+test('ru marker widens the alphabet: Russian prose + typography + ASCII code -> clean', async () => {
+  const md = [
+    '<!-- tackbox: lang=ru personal experimental repo -->',
+    '# ' + PRIVET,
+    '',
+    // em-dash, guillemets, ellipsis, NBSP all allowed under ru
+    PRIVET + ' \u{2014} \u{AB}' + MIR + '\u{BB}\u{2026}\u{A0}end',
+    '',
+    '```bash',
+    'echo hi',
+    '```',
+  ].join('\n')
+  const errs = await run(md)
+  assert.equal(errs.length, 0, JSON.stringify(errs))
+})
+
+test('ru marker still flags emoji and CJK, and only those', async () => {
+  const md = [
+    '<!-- tackbox: lang=ru note -->',
+    PRIVET + ' \u{1F680} \u{4E2D}', // rocket + CJK amid allowed Cyrillic
+  ].join('\n')
+  const errs = await run(md)
+  assert.deepEqual(detailHexes(errs), ['1F680', '4E2D'])
+})
+
+test('no marker: Cyrillic is still flagged (default unchanged)', async () => {
+  const errs = await run(PRIVET + '\n')
+  assert.deepEqual(detailHexes(errs), ['41F', '440', '438', '432', '435', '442'])
+})
+
+test('marker below line 5 is a finding and does not widen', async () => {
+  const md = [
+    'line 1', 'line 2', 'line 3', 'line 4', 'line 5',
+    '<!-- tackbox: lang=ru too late -->',
+    PRIVET, // line 7
+  ].join('\n')
+  const errs = await run(md)
+  const placement = errs.find(e => /within the first 5 lines/.test(e.errorDetail))
+  assert.ok(placement, 'expected a marker-placement finding: ' + JSON.stringify(errs))
+  assert.equal(placement.lineNumber, 6)
+  // File stays ASCII-only, so the Cyrillic on line 7 is still flagged.
+  assert.ok(errs.some(e => e.lineNumber === 7 && /U\+41F/.test(e.errorDetail)))
+})
+
+test('duplicate marker is a finding and leaves the file ASCII-only', async () => {
+  const md = [
+    '<!-- tackbox: lang=ru first -->',
+    '<!-- tackbox: lang=ru second -->',
+    PRIVET,
+  ].join('\n')
+  const errs = await run(md)
+  const dup = errs.filter(e => /duplicate tackbox lang marker/.test(e.errorDetail))
+  assert.equal(dup.length, 1)
+  assert.equal(dup[0].lineNumber, 2)
+  assert.ok(errs.some(e => /U\+41F/.test(e.errorDetail)), 'Cyrillic still flagged')
+})
+
+test('unknown language code is a finding and does not widen', async () => {
+  const errs = await run('<!-- tackbox: lang=xx -->\n' + PRIVET + '\n')
+  assert.ok(errs.some(e => /unsupported language code 'xx'/.test(e.errorDetail)))
+  assert.ok(errs.some(e => /U\+41F/.test(e.errorDetail)))
+})
+
+test('marker with no language code is a finding and does not widen', async () => {
+  const errs = await run('<!-- tackbox: lang= -->\n' + PRIVET + '\n')
+  assert.ok(errs.some(e => /missing a language code/.test(e.errorDetail)))
+  assert.ok(errs.some(e => /U\+41F/.test(e.errorDetail)))
+})

package/js/tests/report.test.js

@@ -0,0 +1,182 @@
+const { test } = require('node:test')
+const assert = require('node:assert')
+
+// report.js reads console, window/CustomEvent, and @sentry/browser at call time
+// (globals + the shared module cache), so replacing them here reaches the module
+// under test. A fake Sentry in require.cache dodges real init/network; load()
+// reloads report.js per scenario for pristine ready/lastSent state.
+const REPORT_PATH = require.resolve('../report.js')
+const SENTRY_PATH = require.resolve('@sentry/browser')
+
+console.log = () => {}
+console.warn = () => {}
+console.error = () => {}
+
+let captured = [] // one entry per Sentry.captureException: { err, level, fingerprint, tags }
+let dispatched = [] // one entry per window.dispatchEvent: the CustomEvent detail
+let scope = null
+
+const fakeSentry = {
+  init() {},
+  withScope(fn) {
+    scope = { level: undefined, fingerprint: undefined, tags: {} }
+    fn({
+      setLevel(l) { scope.level = l },
+      setFingerprint(f) { scope.fingerprint = f },
+      setTag(k, v) { scope.tags[k] = v },
+    })
+    scope = null
+  },
+  captureException(err) {
+    captured.push({
+      err,
+      level: scope && scope.level,
+      fingerprint: scope && scope.fingerprint,
+      tags: scope ? { ...scope.tags } : null,
+    })
+  },
+}
+require.cache[SENTRY_PATH] = { id: SENTRY_PATH, filename: SENTRY_PATH, loaded: true, exports: fakeSentry }
+
+class FakeCustomEvent {
+  constructor(type, opts) {
+    this.type = type
+    this.detail = opts && opts.detail
+  }
+}
+Object.defineProperty(globalThis, 'CustomEvent', { value: FakeCustomEvent, configurable: true, writable: true })
+Object.defineProperty(globalThis, 'window', {
+  value: { addEventListener() {}, dispatchEvent(ev) { dispatched.push(ev.detail); return true } },
+  configurable: true,
+  writable: true,
+})
+
+const VALID_DSN = 'https://public@sentry.example.com/1'
+
+function load() {
+  captured = []
+  dispatched = []
+  scope = null
+  delete require.cache[REPORT_PATH]
+  return require(REPORT_PATH)
+}
+
+// (a) DSN unset -> not ready -> capture disabled, but the user lane still fires.
+test('report dispatches to the user lane even when not ready (DSN unset)', () => {
+  const report = load()
+  report.init({})
+  assert.equal(report.isReady(), false)
+  report.reportError('connection lost mid-stream', new Error('boom'), { area: 'net' }, 'net.conn')
+  assert.equal(dispatched.length, 1, 'user lane must dispatch without init')
+  assert.equal(captured.length, 0, 'capture stays gated off when not ready')
+  assert.equal(dispatched[0].msg, 'connection lost mid-stream')
+  assert.equal(dispatched[0].dedupKey, 'net.conn')
+})
+
+// (b) same dedupKey inside the rate window: both dispatch, second capture dropped.
+test('rate window drops the second capture but never the dispatch', () => {
+  const report = load()
+  report.init({ dsn: VALID_DSN })
+  assert.equal(report.isReady(), true)
+  report.reportError('poll failed on stale token', new Error('e1'), { area: 'poll' }, 'poll.stale')
+  report.reportError('poll failed on stale token', new Error('e2'), { area: 'poll' }, 'poll.stale')
+  assert.equal(dispatched.length, 2, 'every event reaches the user lane')
+  assert.equal(captured.length, 1, 'duplicate capture suppressed within the window')
+})
+
+// (D-5) re-entrancy guard: a throwing tackbox:error listener surfaces via
+// window.onerror, which setupGlobalHandlers turns back into reportError ->
+// dispatch on the same stack. The guard skips the nested dispatch so it cannot
+// loop; sequential dispatches are unaffected.
+test('a re-entering dispatch is skipped (no infinite loop, one outer dispatch)', () => {
+  const report = load()
+  report.init({})
+  let calls = 0
+  const realWindow = window
+  Object.defineProperty(globalThis, 'window', {
+    value: {
+      addEventListener() {},
+      dispatchEvent(ev) {
+        calls++
+        dispatched.push(ev.detail)
+        // the listener failure re-enters synchronously via reportError
+        report.reportError('re-entry from a listener failure', new Error('inner'), null, 'reentry.key')
+        return true
+      },
+    },
+    configurable: true,
+    writable: true,
+  })
+  try {
+    report.reportError('outer dispatch that re-enters', new Error('outer'), null, 'outer.key')
+    assert.equal(calls, 1, 'exactly one dispatch; the nested re-entry is skipped')
+    assert.equal(dispatched.length, 1, 'only the outer notice reaches the user lane')
+  } finally {
+    Object.defineProperty(globalThis, 'window', { value: realWindow, configurable: true, writable: true })
+  }
+})
+
+// (c) reportPanic routes to the user lane with level fatal and a per-name key.
+test('reportPanic dispatches level fatal with panic:<name> dedupKey', () => {
+  const report = load()
+  report.reportPanic('worker', new Error('kaboom'))
+  assert.equal(dispatched.length, 1)
+  const d = dispatched[0]
+  assert.equal(d.level, 'fatal')
+  assert.equal(d.dedupKey, 'panic:worker')
+  assert.equal(d.msg, 'panic in worker')
+  assert.equal(d.cause.message, 'kaboom')
+})
+
+// (d) capture builds Error(msg) with the original error chained as .cause (seed shape).
+test('capture is Error(msg) with the original cause chained', () => {
+  const report = load()
+  report.init({ dsn: VALID_DSN })
+  const original = new Error('socket hangup')
+  report.reportError('upload failed mid-flight', original, { area: 'upload' }, 'upload.fail')
+  assert.equal(captured.length, 1)
+  const { err, level, fingerprint, tags } = captured[0]
+  assert.ok(err instanceof Error)
+  assert.equal(err.message, 'upload failed mid-flight')
+  assert.equal(err.cause, original)
+  assert.equal(level, 'error')
+  assert.deepEqual(fingerprint, ['upload.fail'])
+  assert.equal(tags.area, 'upload')
+})
+
+// (e) reportSynthError captures a plain Error(msg) with no cause chain.
+test('reportSynthError captures Error(msg) with no cause', () => {
+  const report = load()
+  report.init({ dsn: VALID_DSN })
+  report.reportSynthError('non-OK response handled inline', { area: 'http' }, 'http.synth')
+  assert.equal(captured.length, 1)
+  assert.equal(captured[0].err.message, 'non-OK response handled inline')
+  assert.equal(captured[0].err.cause, undefined)
+  assert.equal(dispatched.length, 1)
+  assert.equal(dispatched[0].cause, null, 'synth user-lane detail carries cause: null')
+})
+
+// (f) reportQuiet captures at warning with no user-lane dispatch.
+test('reportQuiet captures warning-level with no user-lane dispatch', () => {
+  const report = load()
+  report.init({ dsn: VALID_DSN })
+  report.reportQuiet('index rebuild degraded, using stale', new Error('timeout'), { area: 'idx' }, 'idx.stale')
+  assert.equal(captured.length, 1, 'quiet still captures')
+  assert.equal(captured[0].level, 'warning')
+  assert.deepEqual(captured[0].fingerprint, ['idx.stale'])
+  assert.equal(dispatched.length, 0, 'quiet must not touch the user lane')
+})
+
+// (g) notify dispatches only, captures nothing, and consumes no rate slot.
+test('notify dispatches level notice, captures nothing, leaves the rate slot', () => {
+  const report = load()
+  report.init({ dsn: VALID_DSN })
+  report.notify('you appear to be offline', new Error('net down'), { area: 'conn' }, 'conn.offline')
+  assert.equal(dispatched.length, 1)
+  assert.equal(dispatched[0].level, 'notice')
+  assert.equal(captured.length, 0, 'notify captures nothing')
+  // Same dedupKey still captures: notify consumed no rate slot.
+  report.reportError('still offline after retry', new Error('net down'), { area: 'conn' }, 'conn.offline')
+  assert.equal(captured.length, 1, 'following reportError on the notify key still captures')
+  assert.equal(dispatched.length, 2)
+})