Step one towards stable error messages with details:

pkg/code_transformers/lib/src/messages.dart

+// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Contains all warning messages produced by the code_transformers package.
+library code_transformers.src.messages;
+
+import 'package:code_transformers/messages/messages.dart';
+
+const noAbsolutePaths = const MessageTemplate(

[jakemac, 2014/09/03 17:20:41]

These should really be all caps names since they are global constants
(throughout)

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

:) I think there is not consensus on that part of the style guide, that's why I
didn't use them here (see
https://github.com/dart-lang/www.dartlang.org/issues/831)

[jakemac, 2014/09/04 14:42:37]

Weird, but ok :). To me all caps constants is the universal way of defining
constants, so I would personally agree with the style guide (as it stands now)
in this case. I am curious what the argument is against that? The existing bug
doesn't really say why other than it creates a breaking change if you change
something from final to const, which we could leave in an exception for.

On 2014/09/04 02:32:13, Siggi Cherem (dart-lang) wrote:

+    const MessageId('code_transformers', 1),
+    'absolute paths not allowed: "%-url-%"',
+    'Absolute paths not allowed',
+    '''
+The transformers processing your code were trying to resolve a URL and identify
+a file that they correspond to. Currently only relative paths can be resolved.
+''');
+
+const invalidUrlToOtherPackage = const MessageTemplate(
+    const MessageId('code_transformers', 2),
+    'Invalid url to reach to another package: %-url-%. Path '

[Kathy Walrath, 2014/09/03 18:56:36]

Global change to text:
url -> URL

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    'reaching to other packages must first reach up all the '
+    'way to the %-prefix-% folder. For example, try changing the url above '

[Kathy Walrath, 2014/09/03 18:56:35]

is it clear what "above" means?

[Kathy Walrath, 2014/09/03 18:56:36]

Be consistent about using folder vs. directory. I believe that in the docs we
usually use "directory".

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

Done.

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

It seems we didn't need it :). removed

+    'to: %-fixedUrl-%',
+    'Invalid url to reach another package',
+    '''
+To reach an asset that belongs to another package, we use `package:` URLs in

[Kathy Walrath, 2014/09/03 18:56:35]

we use -> use

In general, avoid "we" in messages. It's unclear who "we" is, and usually not
necessary.

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+Dart code, but in any other language (like HTML or CSS) we use relative URLs.

[Kathy Walrath, 2014/09/03 18:56:36]

we use -> use

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

Done.

+
+These are the rules you must follow to write URLs that refer to files in other

[Kathy Walrath, 2014/09/03 18:56:35]

-> Follow these rules when writing...

This is way long, so I'll create a document that contains these rules. (You can
ignore the rest of the comments on this message!)

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

I was debating about this - one idea I was thinking is that we can make such
document the output of compiling this file. Instead of maintaining a separate
place for documentation, each error is documented with the code here.  Note that
the first 3 lines (21-23) is what the user sees in the command-line or pub-serve
as the error message, this part of the message is only visible if they click on
a link to see 'more details'.

It might be easier to chat about this face-to-face, let me know. 

+packages:
+
+  * if the file containing the relative URL is an entrypoint under `web`, use

[Kathy Walrath, 2014/09/03 18:56:36]

if -> If

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    `packages/package_name/path_to_file`
+
+  * if the file containing the URL is under `web`, but on a different directory

[Kathy Walrath, 2014/09/03 18:56:35]

if -> If
on -> in

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

Done.

+    than your entrypoint, walk out to the same level as the entrypoint first,
+    then enter the `packages` folder.
+
+    **Note**: this means that if you have two entrypoints including this file,

[Kathy Walrath, 2014/09/03 18:56:36]

this means that if you have two entrypoints including
->
If two entrypoints include

this file -> the same file that's under `web` (? "this file" didn't seem clear
enough)

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    either both entrypoints have to live in the same directory, or you need to
+    move the file to the `lib` folder.
+
+  * if the file containing the URL lives under `lib`, walk up as many levels as

[Kathy Walrath, 2014/09/03 18:56:36]

if -> If

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    directories you have + 1. This is because code in `lib/a/b` is loaded from
+    `packages/package_name/a/b`.
+
+The rules are easier to follow if you know how the code is layed out for

[Kathy Walrath, 2014/09/03 18:56:35]

layed -> laid

(global)

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

<facepalm> thx!

[Kathy Walrath, 2014/09/04 17:07:28]

I had to look it up to be sure. :)

+Dartium before you build, and how it is layed out after you build it with `pub
+build`. Consider the following example:
+
+   package a
+      lib/
+        '- a1.html

[Kathy Walrath, 2014/09/03 18:56:35]

Could you use | instead of '? You used | below (for c/web/c1), and it seemed
clearer to me.

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

Sure, I was basically using the style that pub uses on the command-line (the
last entry is a bit shorter with ' instead of | )

+
+      web/
+        '- a2.html
+
+   package b
+      lib/
+        |- b1.html
+        '- b2/
+            '- b3.html
+
+   package c
+      lib/
+        '- c3.html
+
+      web/
+        |- index.html
+        |- index.dart
+        |- c1/
+            '- c2.html
+
+If your app is package `c`, you'll notice that in your file system there is a

[Kathy Walrath, 2014/09/03 18:56:36]

you'll notice that in your file system there is a packages folder generate in
the web folder
->
then `pub build` generates a packages folder under the web folder

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

Done.

+packages folder generated in the web folder, like this:
+
+      web/
+        |- index.html
+        |- index.dart
+        |- c1/
+        |   '- c2.html
+        '- packages/
+            |- a/
+            |   '- a1.html
+            |- b/
+            |   |- b1.html
+            |   '- b2/
+            |       '- b3.html
+            '- c/
+                '- c3.html
+
+Note that there is no `lib` folder under the `packages` folder. When you load
+`index.html` in Dartium, it will infer that the package root is under

[Kathy Walrath, 2014/09/03 18:56:35]

what is "it"? Also, avoid "there is" when possible. Finally, I found myself
getting a bit confused about whether this was really `pub build` output, since
no `build` directory was visible. This seemed like it might be just `pub get`
output.

Maybe:

Note that no `lib` directory is under the `packages` directory.
When Dartium loads `web/index.html`, Dartium infers that the package root
is under `web/packages/`.

I'm not sure "infers" is the right word here, but maybe it is. Maybe it's more
like this:

...Dartium loads libraries from package roots directly under `web/packages`.

[Siggi Cherem (dart-lang), 2014/09/04 02:32:13]

Good points. Thanks - here is what I ended up with:

Note that no `lib` directory is under the `packages` directory.
When you launch `web/index.html` in Dartium, Dartium loads `package:` imports
from
`web/packages/`.

+`web/packages/`.
+
+If you need to refer to any file in other packages from `index.html`, you can
+simply do `packages/package_name/path_to_file`. For example
+`packages/b/b2/b3.html`. From `index.html` you can also refer to files under the
+web folder of the same package using a simple relative URL, like `c1/c2.html`.
+
+However, if you want to load `a1.html` from `c2.html`, you need to reach out to
+the packages folder that lives next to your entrypoint and then load the file
+from there, for example `../packages/a/a1.html`. Because pub generates symlinks
+to the packages folder also under c1, you may be tempted to write
+`packages/a/a1.html`, but that is incorrect - it would yield a canonicalization
+error (see more below).
+
+If you want to load a file from the lib folder of your own package, you
+should also use a package URL. For example, `packages/c/c3.html` and not
+`../lib/c3.html`. This will allow you to write code in `lib` in a way that it
+can be used within and outside your package without making any changes to it.
+
+Because any time you reach inside a `lib/` folder you do so using a `packages/`
+URL, the rules for reaching into other files in other packages are always
+consistent: go up to exit the `packages` folder and go back inside to the file you
+are looking for.  For example, to reach `a1.html` from `b3.html` you need to
+write `../../../packages/a/a1.html`.
+
+The motivation behind all these rules is that we would like to have URLs that
+work under many scenarios at once:
+
+  * They need to work in Dartium without any code transformation: resolving the
+    path in the context of a simple HTTP server, or using `file:///` URLs,
+    should yield a valid path to assets. Since pub already creates a `packages`
+    directory next to entrypoints of your application, we assume we can use it.
+
+  * They need to be canonical. To take advantage of caching, multiple URLs
+    reaching the same asset should resolve to the same absolute URL.
+    
+    Also, in projects that use HTML imports (like polymer) we make sure that if
+    you reach a library twice, once with Dart imports, and a second time with
+    HTML imports, then they are correctly resolved to be the same library. Our
+    rules are designed to allow tools to ensure this.
+
+    For example, consider you have an import might like:
+
+        <link rel=import href=packages/a/a.html>
+
+    where a.html has `<script type="application/dart" src="a.dart">`. If your
+    Dart entrypoint also loads `"package:a/a.dart"`,  then we need to make sure
+    that both versions of `a.dart` are loaded from the same URL. Otherwise, you
+    may see errors at runtime like: `A is not a subtype of A`, which can be
+    extremely confusing.
+
+    When you follow the rules above, our tools can detect the pattern in the
+    HTML-import URL containing `packages/` and canonicalize the import
+    by converting `packages/a/a.dart` into `package:a/a.dart` under the hood.
+
+  * They need to continue to be valid after applications are built.
+    Technically this could be done automatically with pub transformers, but to
+    make sure that code works also in Dartium with a simple HTTP Server,
+    existing transformers do not fix URLs, they just detect inconsistencies and
+    produce an error message like this one, instead.

[Kathy Walrath, 2014/09/03 18:56:36]

This is a lot of doc! How about I put it in a page, so we can have real figures
and it's more easily editable. It seems like these messages should give a hint
and then link to the doc page. 

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

That's actually how it works, I'm just storing the longer explanation here too. 

The hint is just the second parameter to MessageTemplate. In this case:

  Invalid URL to reach to another package: %-url-%. Path reaching to other
packages must first reach up all the way to the %-prefix-% directory. For
example, try changing the URL to: %-fixedUrl-%.

(where %-name-% are replaced with the tokens from the user's code)

[Kathy Walrath, 2014/09/04 17:07:27]

What I meant was I didn't want to bury this doc (about import paths) on this
page. It deserves its own page, which you could link to. (And of course it
shouldn't be in two pages, because then it's likely to get out of sync and
confuse people.) I'll send you a CL today.

+''');
+
+const incompletePrefixPath = const MessageTemplate(
+    const MessageId('code_transformers', 3),
+    'incomplete %-prefix-%/ path. It should have at least 3 '
+    'segments %-prefix-%/name/path_from_name\'s_%-folder-%_dir',
+    'Incomplete import to asset in another package',

[Kathy Walrath, 2014/09/03 18:56:36]

to -> of?

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

rephrased, I should not use the word import here anyways

+    '''
+Currently we require that URLs that refer to assets in other packages to
+explicitly mention the `packages/` folder. In the future we might remove this
+requiremnt, but for now we ask that you use a canonical URL form for it.

[Kathy Walrath, 2014/09/03 18:56:36]

requiremnt -> requirement

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+
+For example, if you have `packages/a/a.html` using an HTML import to
+`packages/b/b.html`, you could technically just write `../b/b.html`, but we

[Kathy Walrath, 2014/09/03 18:56:35]

who is "we" really? polymer.dart? The polymer transformer? Maybe it doesn't
really matter?

Maybe:

For example, if `packages/a/a.html` needs to import `packages/b/b.html`,
you might expect a.html to import `../b/b.html`. Instead, it must import
`../../packages/b/b.html`.
See ...

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done. also removed `we` elsewhere...

+require that you write `../../packages/b/b.html`.
+See [issue 15797](http://dartbug.com/15797).
+''');