tewip-ai 0.47.0 → 0.49.0

package/README.md

@@ -38,6 +38,36 @@ never goes to the model again.
 Tewip prints what every command costs, caps its own spend, and works with no key at all - the rules
 run on their own and everything they cannot settle is left as UNKNOWN rather than guessed.
 
+## Start here
+
+```bash
+npm i -g tewip-ai
+cd your-project
+tewip
+```
+
+`tewip` on its own looks at **your** project and names the two or three commands that will tell you
+something, with your own paths in them — and says plainly what it cannot answer here. It reads the
+directory and stops: nothing is run, nothing is written, about a second.
+
+```
+Here is what Tewip can tell you about **this** project, in the order worth doing.
+
+**1. `tewip vouch`**
+282 test files here (282 JavaScript or TypeScript). This reads them and names the ones
+that cannot fail - no model, a second or two.
+
+**2. `tewip schema --diff main...HEAD`**
+165 migrations here (165 SQL). This says what a change would do to a live database
+before it runs.
+
+## What it will not do here
+- No k6, JMeter or Lighthouse report was found. Tewip judges one you produce; it does
+  not run load tests itself.
+```
+
+Everything below is the full list, for when you want it.
+
 ## Use it in your project
 
 **Giving it to your team (or another company): [TEAM-GUIDE.md](TEAM-GUIDE.md)** — what to install, what each role uses it for, and what it never does.
@@ -897,7 +927,7 @@ That last section is the part no SQL linter does: it searches your own code for
 away. "This drops `users.nickname`, and four files still read it" is a different sentence from "dropping a
 column is risky", and it is the one that stops the outage.
 
-It reads **SQL, Django, Rails, Alembic, TypeORM, Sequelize, Knex, EF Core and Liquibase** migrations — which covers Prisma, Drizzle, Flyway
+It reads **SQL, Django, Rails, Alembic, TypeORM, Sequelize, Knex, Laravel, EF Core and Liquibase** migrations — which covers Prisma, Drizzle, Flyway
 and golang-migrate too, since those all emit plain `.sql`. It judges **only the forward path** (a rollback step
 contains the mirror image of the change, so reading it says a migration that creates a table destroys
 one), and stays quiet when the team already did the safe thing — `atomic = False`, `algorithm:

package/dist/cli/help.js

@@ -4,6 +4,11 @@
 export const HELP = `Tewip - finds why each test failed, for any stack.
 
 Usage:
+  tewip                             Look at this project and name the two or three commands that
+  tewip start                       will tell you something about it, with your own paths in them,
+                                    and say plainly what Tewip cannot answer here. Reads the
+                                    directory and stops: nothing is run and nothing is written.
+                                    Start here. Everything below is the full list.
   tewip explain <report>            Explain a test report: a JUnit XML or .trx file, a folder of
                                     them, or a Playwright blob-report folder. Keeps history per
                                     project, so later runs are judged against earlier ones.
@@ -162,7 +167,7 @@ Usage:
                                     that break the version still running during a deploy, destroy data,
                                     block writes while they run, or cannot be undone - and searches your
                                     code for what still uses the column it takes away. Reads SQL,
-                                    Django, Rails, Alembic, TypeORM, Sequelize, Knex, EF Core and
+                                    Django, Rails, Alembic, TypeORM, Sequelize, Knex, Laravel, EF Core and
                                     Liquibase - so Prisma, Drizzle, Flyway and golang-migrate too,
                                     since those emit plain SQL - and says so when it cannot read one.
                                     It judges only the forward path, never the rollback. No cost.

package/dist/cli/tewip.js

@@ -237,7 +237,16 @@ async function main() {
         case '-v':
             console.log(version());
             return;
+        // `tewip` on its own used to print 233 lines of help, which is a reference for somebody who
+        // already knows what they want and a wall for everybody else. It now looks at the project and
+        // names the two or three commands that will tell *this* team something. --help is unchanged
+        // and still has all of it.
         case undefined:
+        case 'start': {
+            const { runStart } = await import('../engine/start/start-command.js');
+            runStart(process.cwd());
+            return;
+        }
         case '--help':
         case '-h':
         case 'help':

package/dist/engine/access/markup.js

@@ -50,7 +50,23 @@ function withoutNonMarkup(source, jsLike) {
         .replace(/\{\/\*[\s\S]*?\*\/\}/g, blank)
         .replace(/<script\b[\s\S]*?<\/script\s*>/gi, blank)
         .replace(/<style\b[\s\S]*?<\/style\s*>/gi, blank);
-    return jsLike ? stripped.replace(/`(?:[^`\\]|\\[\s\S])*`/g, blank) : stripped;
+    // A template expression is code, not markup, and real templates put markup *inside* it: GOV.UK's
+    // own examples gallery passes `{{ govukLabel({ "text": "<h1> govuk-label--xl" }) }}`, and reading
+    // that `<h1>` as a heading poisoned the outline so badly that twelve heading skips were reported
+    // on a page whose headings are perfectly ordered - on the design system built by the UK
+    // government's accessibility specialists, which is as wrong as this check can be.
+    //
+    // The delimiters are kept and only the contents blanked, which matters: `<button>{{ label }}</button>`
+    // must still read as content this file cannot see, so the button is asked about rather than
+    // called empty, and `alt="{{ alt }}"` must still count as an alt attribute that is present.
+    const withoutExpressions = stripped
+        // A template comment is a comment: Jinja, Nunjucks and Twig write `{# ... #}`, and Django and
+        // Jinja also have a `{% comment %}` block. Neither renders, so neither is markup.
+        .replace(/\{#[\s\S]*?#\}/g, blank)
+        .replace(/\{%-?\s*comment\s*-?%\}[\s\S]*?\{%-?\s*endcomment\s*-?%\}/gi, blank)
+        .replace(/\{\{[\s\S]*?\}\}/g, (m) => `{{${m.slice(2, -2).replace(/[^\n]/g, ' ')}}}`)
+        .replace(/\{%[\s\S]*?%\}/g, (m) => `{%${m.slice(2, -2).replace(/[^\n]/g, ' ')}%}`);
+    return jsLike ? withoutExpressions.replace(/`(?:[^`\\]|\\[\s\S])*`/g, blank) : withoutExpressions;
 }
 /** Files whose markup is embedded in JavaScript, where a backtick string is not page markup. */
 export const JS_LIKE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/i;

package/dist/engine/schema/dialect-rules.js

@@ -144,4 +144,51 @@ const ALEMBIC = [
 // empty on purpose and every finding comes from reading that SQL, which is the same reader the
 // `.sql` dialect uses. The exhaustive Record is what made this a compile error rather than a
 // TypeORM migration silently producing no findings at all.
+/**
+ * Laravel. Found missing by running Tewip over firefly-iii, a real finance application with **61
+ * migrations Tewip could not read a word of** - and Laravel is one of the most used web frameworks
+ * there is, while `schema` advertised nine dialects.
+ *
+ * Structurally it is Knex's shape: the table is named by `Schema::table('accounts', ...)` and the
+ * operation happens inside the closure, so the two are matched together across the lines between.
+ */
+export const LARAVEL = [
+    {
+        find: new RegExp(String.raw `Schema::(?:table|connection\(.*?\)->table)\(\s*${STR}[\s\S]{0,600}?->dropColumn\(\s*${STR}`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `drops ${m[1]}.${m[2]}`,
+        instead: 'deploy code that no longer selects or writes the column, then drop it in a later migration. Eloquent caches the column list, so the running version keeps selecting it',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `Schema::(?:table|connection\(.*?\)->table)\(\s*${STR}[\s\S]{0,600}?->renameColumn\(\s*${STR}`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `renames ${m[1]}.${m[2]}`,
+        instead: 'add the new column, write to both, move the readers, then remove the old one',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `Schema::drop(?:IfExists)?\(\s*${STR}`, 'i'),
+        risk: 'destroys-data',
+        what: (m) => `drops the table ${m[1]}`,
+        instead: 'stop reading the table, deploy that, then drop it once nothing refers to it',
+        table: (m) => m[1],
+    },
+    {
+        find: new RegExp(String.raw `Schema::(?:table|connection\(.*?\)->table)\(\s*${STR}[\s\S]{0,600}?->index\(`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `builds an index on ${m[1]} while holding a lock that blocks writes to it`,
+        instead: 'build it with a raw CREATE INDEX CONCURRENTLY through DB::statement, or accept the lock if the table is small',
+        table: (m) => m[1],
+    },
+    {
+        find: new RegExp(String.raw `Schema::(?:table|connection\(.*?\)->table)\(\s*${STR}[\s\S]{0,600}?->foreign\(`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `adds a foreign key to ${m[1]}, which checks every existing row under a lock on both tables`,
+        instead: 'add it NOT VALID and validate it afterwards, which takes a weaker lock',
+        table: (m) => m[1],
+    },
+];
 export { DJANGO, RAILS, ALEMBIC };

package/dist/engine/schema/frameworks.js

@@ -1,4 +1,4 @@
-import { ALEMBIC, DJANGO, RAILS } from './dialect-rules.js';
+import { ALEMBIC, DJANGO, LARAVEL, RAILS } from './dialect-rules.js';
 import { EFCORE, KNEX, LIQUIBASE, SEQUELIZE } from './dialect-rules-node.js';
 export function dialectOf(file, text) {
     const path = file.split('\\').join('/').toLowerCase();
@@ -17,6 +17,10 @@ export function dialectOf(file, text) {
     // strings passed to queryRunner.query(). The SQL is right there and perfectly readable; only the
     // wrapper was unfamiliar, so every TypeORM project was told Tewip could not read its migrations
     // at all - and on a Node backend that is most of them.
+    // Laravel, before the generic checks: its migrations are PHP and would otherwise fall through
+    // to 'unknown'. firefly-iii has 61 of them and Tewip could not read a word.
+    if (/Illuminate.Database.Migrations.Migration|\bSchema::(?:table|create|drop|dropIfExists|connection)\s*\(/.test(text))
+        return 'laravel';
     if (/\bMigrationInterface\b|\bqueryRunner\.query\s*\(/.test(text))
         return 'typeorm';
     if (/\bqueryInterface\.\w+\s*\(/.test(text))
@@ -40,6 +44,7 @@ const BY_DIALECT = {
     knex: KNEX,
     efcore: EFCORE,
     liquibase: LIQUIBASE,
+    laravel: LARAVEL,
 };
 /** Findings from a framework migration, with the line each one sits on. */
 export function readFramework(dialect, text) {
@@ -111,6 +116,8 @@ export function forwardOnly(dialect, text) {
             (dialect === 'sequelize' && /^\s*down\s*:/.test(line)) ||
             (dialect === 'knex' && /^\s*(?:exports\.down|module\.exports\.down)\s*=/.test(line)) ||
             (dialect === 'efcore' && /^\s*protected\s+override\s+void\s+Down\s*\(/.test(line)) ||
+            // Laravel's rollback, which in real files often comes *before* up().
+            (dialect === 'laravel' && /^\s*(?:public\s+)?function\s+down\s*\(/.test(line)) ||
             // Liquibase puts the reverse inside the change itself rather than in a second method.
             (dialect === 'liquibase' && /^\s*<rollback\b/.test(line));
         if (down) {

package/dist/engine/schema/schema-command.js

@@ -70,7 +70,7 @@ export function readMigration(root, file) {
             file,
             dialect,
             findings: [],
-            unread: 'Tewip does not recognise how this migration is written, so it says nothing about it rather than passing it. It reads SQL, Django, Rails, Alembic, TypeORM, Sequelize, Knex, EF Core and Liquibase migrations',
+            unread: 'Tewip does not recognise how this migration is written, so it says nothing about it rather than passing it. It reads SQL, Django, Rails, Alembic, TypeORM, Sequelize, Knex, Laravel, EF Core and Liquibase migrations',
             irreversible: false,
         };
     }

package/dist/engine/start/start-command.js

@@ -0,0 +1,216 @@
+// `tewip` with nothing after it: look at this project and say what Tewip can actually do for it.
+//
+// Until now the answer to "I installed it, now what" was 233 lines of help listing eleven commands,
+// which is a reference for somebody who already knows what they want and a wall for everybody else.
+// Eleven commands is already more than most teams will run; the problem was never the number of
+// things Tewip can do, it was that none of them were connected to *this* repository.
+//
+// So this looks. It counts what is actually here - test files and which framework wrote them,
+// migrations and which tool, markup and which template language, a k6 or JMeter or Lighthouse
+// report somebody has already produced - and then names the two or three commands that will tell
+// this team something, with their own paths in them. And it says what Tewip cannot do here, because
+// a front door that implies it can do everything is the same lie as a report with no limits on it.
+//
+// Nothing is run and nothing is written. It reads the directory and stops.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { languageOf, looksLikeTests } from '../vouch/tests-in.js';
+import { MARKUP } from '../access/markup.js';
+import { dialectOf } from '../schema/frameworks.js';
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'out', 'coverage', 'target', 'vendor', '__pycache__', '.venv', 'venv', '.next', '.cache', '.tewip', '.triage-agent']);
+/**
+ * A bounded look: enough to recognise a project, not enough to be slow on a large one.
+ *
+ * Breadth-first, and that is the whole correctness of it. Depth-first with a budget spends the
+ * budget wherever the alphabet happens to lead: pointed at Tewip itself it descended into `data/`,
+ * exhausted 4000 files on stored datasets, and reported **7 test files in a repository with 69**.
+ * A number that wrong is worse than no number, because the front door is the one place a person
+ * has no way to tell. Breadth-first sees every top-level directory before descending into any of
+ * them, so the budget is spent on breadth, which is what recognising a project needs.
+ */
+export function lookAround(root, limit = 4000) {
+    const found = {
+        tests: new Map(),
+        migrations: new Map(),
+        markup: 0,
+        perfReports: [],
+        hasWorkflows: existsSync(join(root, '.github', 'workflows')),
+        hasStandards: existsSync(join(root, '.tewip', 'standards')),
+        filesSeen: false,
+    };
+    let seen = 0;
+    // A queue rather than recursion: every directory at one depth is read before any at the next.
+    const queue = [{ dir: root, depth: 0 }];
+    while (queue.length > 0 && seen < limit) {
+        const { dir, depth } = queue.shift();
+        if (depth > 8)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (seen >= limit)
+                break;
+            if (SKIP.has(entry) || (entry.startsWith('.') && entry !== '.github'))
+                continue;
+            const full = join(dir, entry);
+            let info;
+            try {
+                info = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (info.isDirectory()) {
+                queue.push({ dir: full, depth: depth + 1 });
+                continue;
+            }
+            seen += 1;
+            found.filesSeen = true;
+            const rel = relative(root, full).replaceAll('\\', '/');
+            if (MARKUP.test(entry))
+                found.markup += 1;
+            if (/\.jtl$/i.test(entry))
+                found.perfReports.push(rel);
+            else if (/(k6|lighthouse|summary|lhr)[\w.-]*\.json$/i.test(entry) && info.size < 8_000_000)
+                found.perfReports.push(rel);
+            const inMigrations = /(^|\/)(migrations?|db\/migrate|changelog)\//i.test(rel);
+            // Reading a file is only worth it for the two questions a name cannot answer: is this a
+            // test, and is this a migration. Both are cheap, and both are often wrong from the path.
+            const language = languageOf(entry);
+            const worthReading = (language !== null || /\.(sql|xml)$/i.test(entry)) && info.size < 1_000_000;
+            if (!worthReading)
+                continue;
+            let text = '';
+            try {
+                text = readFileSync(full, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (language && looksLikeTests(rel, text))
+                found.tests.set(language, (found.tests.get(language) ?? 0) + 1);
+            if (inMigrations) {
+                const dialect = dialectOf(rel, text);
+                if (dialect !== 'unknown')
+                    found.migrations.set(dialect, (found.migrations.get(dialect) ?? 0) + 1);
+            }
+        }
+    }
+    return found;
+}
+const total = (counts) => [...counts.values()].reduce((a, b) => a + b, 0);
+/** What a person calls these, rather than what the code calls them. */
+const PLAIN = {
+    js: 'JavaScript or TypeScript',
+    python: 'Python',
+    jvm: 'Java, Kotlin or Scala',
+    go: 'Go',
+    csharp: 'C#',
+    ruby: 'Ruby',
+    php: 'PHP',
+    rust: 'Rust',
+    sql: 'SQL',
+    django: 'Django',
+    rails: 'Rails',
+    alembic: 'Alembic',
+    typeorm: 'TypeORM',
+    sequelize: 'Sequelize',
+    knex: 'Knex',
+    efcore: 'EF Core',
+    liquibase: 'Liquibase',
+};
+const named = (counts) => [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    // Only the ones worth naming: a repository with one stray file in a ninth language does not
+    // need all nine listed at the front door.
+    .slice(0, 3)
+    .map(([name, n]) => `${n} ${PLAIN[name] ?? name}`)
+    .join(', ');
+/** The two or three things worth running here, most useful first. */
+export function suggest(found) {
+    const out = [];
+    const tests = total(found.tests);
+    const migrations = total(found.migrations);
+    if (tests > 0) {
+        out.push({
+            command: 'tewip vouch',
+            because: `${tests} test ${tests === 1 ? 'file' : 'files'} here (${named(found.tests)}). This reads them and names the ones that cannot fail - no model, a second or two.`,
+        });
+    }
+    if (migrations > 0) {
+        out.push({
+            command: 'tewip schema --diff main...HEAD',
+            because: `${migrations} ${migrations === 1 ? 'migration' : 'migrations'} here (${named(found.migrations)}). This says what a change would do to a live database before it runs.`,
+        });
+    }
+    if (found.markup > 0) {
+        out.push({
+            command: 'tewip access',
+            because: `${found.markup} markup ${found.markup === 1 ? 'file' : 'files'} here. This names who cannot use the interface, against the WCAG criterion a regulator would cite.`,
+        });
+    }
+    for (const report of found.perfReports.slice(0, 1)) {
+        out.push({
+            command: `tewip perf ${report}`,
+            because: 'there is already a performance report here, and Tewip will judge it rather than restate it.',
+        });
+    }
+    if (tests > 0) {
+        out.push({
+            command: 'tewip done',
+            because: 'the one verdict over your current change, once you have made one. It answers ready, not ready, or cannot say.',
+        });
+    }
+    return out;
+}
+export function renderStart(found, root) {
+    const lines = ['# Tewip', ''];
+    if (!found.filesSeen) {
+        lines.push(`There is nothing to read in \`${root}\`. Run Tewip from the root of a project.`, '');
+        return lines.join('\n');
+    }
+    const suggestions = suggest(found);
+    if (suggestions.length === 0) {
+        lines.push(`Tewip looked around \`${root}\` and found nothing it can judge: no test files, no migrations, no markup, ` +
+            'and no performance report. That is an honest answer rather than a failure - point it at a project with ' +
+            'tests in it, or run `tewip --help` for the full list.', '');
+        return lines.join('\n');
+    }
+    lines.push('Here is what Tewip can tell you about **this** project, in the order worth doing.', '');
+    for (const [i, s] of suggestions.entries()) {
+        lines.push(`**${i + 1}. \`${s.command}\`**`, '', s.because, '');
+    }
+    lines.push('## What it will not do here', '');
+    const cannot = [];
+    if (total(found.tests) === 0)
+        cannot.push('No test files were found, so nothing can be said about whether your tests could fail or would catch a bug.');
+    if (total(found.migrations) === 0)
+        cannot.push('No migrations were found, so nothing is said about your database.');
+    if (found.markup === 0)
+        cannot.push('No markup was found, so nothing is said about accessibility.');
+    if (found.perfReports.length === 0)
+        cannot.push('No k6, JMeter or Lighthouse report was found. Tewip judges one you produce; it does not run load tests itself.');
+    if (!found.hasStandards)
+        cannot.push('This project has not taught Tewip any house rules yet. Put a markdown file in `.tewip/standards/` and `tewip standards` will enforce it.');
+    if (!found.hasWorkflows)
+        cannot.push('There is no GitHub Actions workflow here. `uses: hmamut39/tewip@main` with `mode: check` runs these same checks on every pull request.');
+    else
+        cannot.push('You have GitHub Actions. `mode: check` runs these same checks on every pull request.');
+    for (const line of cannot)
+        lines.push(`- ${line}`);
+    lines.push('');
+    lines.push('Everything Tewip answers carries its evidence and says what it did **not** check. It answers ' +
+        '"cannot say" rather than guessing. `tewip --help` has all eleven commands when you want them.', '');
+    return lines.join('\n');
+}
+export function runStart(root) {
+    const where = resolve(root);
+    const report = renderStart(lookAround(where), where);
+    console.log(report);
+    return report;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "mcpName": "io.github.hmamut39/tewip",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [